Syniverse Consent Management User guide

Avatar
Kola Layokun
Follow

Overview

Syniverse Consent Management is a managed solution available with your SCG (Syniverse Communication Gateway) SMS service. This solution provides businesses the flexibility to have Syniverse add a managed consent layer to their service that primarily manages the consent status, tracking, and auditing to ensure compliance with local laws and regulations. 

Below is a user guide on how managed consent works and how to use it. Please note that a subscription to the Consent Management service is required along with a fully provisioned Shortcode.

Capturing Consent (End-user Opt-in)

There are 2 main methods of capturing use consent for Messaging campaigns:

  1. Single Opt-in consent: This is usually when a user responds to a request to receive SMS or MMS messages on their mobile number from a business. The most common single opt-in use case is a user responding to a request by sending a MO (Mobile originated) message from their mobile number with a specific “Keyword” in the body of a message to a Customer’s shortcode.

For example:

  • End-user sends Keyword= START to Customer’s Shortcode 55555 from the user’s mobile number.
  • Syniverse’s check to see if the Shortcode is provisioned as Syniverse managed and if so processes the consent request by marking the user as Opt-in (consent_status =OPTIN) and associates this with Customer’s Shortcode
  • Syniverse also sends the Customer a MO event with the message body = "Keyword" to their application via a webhook if present.
  • A customizable welcome message is sent to the end-user e.g 

{"Welcome to Syniverse Communication gateway! Msg&data may apply. Reply HELP for help, Reply STOP to cancel"}

This Opt-in method is known as Single Opt-in as a confirmation of the intent to consent to receiving messages from the Customer is not required.

 

CM2-_A.png

  1. Double Opt-in Consent: This type of consent is usually required when a business is capturing the consent of a user to receive SMS or MMS messages from the Business. This involves an initial capture of a user’s mobile number either via a Web application, a POS interaction or via a mobile application. The Business then initiates a secondary Opt-in by sending a confirmation message to the captured Mobile number to validate and confirm that the user intends to give the required consent.

For example: 

  • Customer sends a consent request <Solicit Consent> to Syniverse via API with end-user’s Mobile number
  • Syniverse processes the request and sends a confirmation message via SMS to the supplied Mobile number.
  • End-user replies with a Yes or NO to the confirmation message
  • If End-user replies with a Yes, Syniverse sends a Welcome CTA message (customizable by Customer) to the end-user
  • Syniverse also send a MO event with a Message body = Yes to the Customer’s webhook
  • Syniverse processes and stores the consent record (consent_status = OPTIN) with the end-user’s mobile number associated with the Customer’s shortcode

This Opt-in method is known as Double Opt-in as a confirmation of the intent to consent to receiving messages from the Customer is required.

CM2-B.png

Using the Syniverse Consent Management service

The Syniverse consent management service is integrated with your SMS service. You can make REST calls via the API to perform the following functions:

Please note that prior to invoking any of these commands below, you must have signed up for the Syniverse consent management service and have it provisioned with a valid Shortcode and a valid Carrier approved Messaging Campaign. Other key information you need to have includes:

  • Campaign Keywords (If single Opt-in) e.g. START, JOIN, MOVIES etc.
  • Welcome Message (Optional), If none is provided, Syniverse will use default
  • Opt-out message (Optional), if none is provided, Syniverse will use default.

Please note that the above key info need to be provided to Syniverse prior to activating consent management service

 

Send <Solicit Consent>: This command lets you submit a request to seek an End-user’s consent if you acquired their mobile number via a channel that is not SMS for instance Web, App, POS, walk-ins. The request will trigger a confirmation MT to complete a double Opt-in consent flow.

**Note that Customers dont have to trigger SMS MO opt-ins. This is usually triggered when an end-user sends a MO SMS message to your configured Opt-in keyword

Sample Request:

curl -X POST -H "Authorization: Bearer d17f79e76e30d7a0f05e6456b0bbc78a" -H "Content-Type: application/json" -d '{"address_type":"LONGCODE","address":"+14085551212","sender_id":"i7GQ7hxAmiDsIArveY3qm3"}' https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses

where:

 

  1. <List Consent status>: This command lets you list the status of all the end-user’s mobile number associated with your shortcode in the Consent Management database. Please note that if you have other Programs in your account with Mobile numbers that are not associated with a Syniverse managed sender address (shortcode), those numbers will be listed too, but they will have a different value in the “consent status” field. See sample below

Sample Request

curl -X GET -H "Authorization: Bearer d17f79e76e30d7a0f05e6555b0bbc78a" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses

where:

Sample Result

 {
 "application_id": 2305,
 "company_id": 1512,
 "created_date": 1553809333006,
 "last_updated_date": 1554416172279,
 "version_number": 2,
 "id": "h05iW1neHgo19pYMmAQ6s4",
 "address_type": "LONGCODE",
 "address": "+14085551212",
 "sender_id": "qvPzyySQq4LBgvzbgpnNH1",
 "consent_status": "OPTOUT",
 "from_address": "55555",
 "opt_in_type": "SMS",
 "opt_out_type": "SMS"
 }

Consent Status values:

  • OPTIN: Messages will be sent to end-user with this value
  • OPTOUT: Messages will not be sent to end-users with this value
  • NONE: Messages will be sent to end-user as this is assumed to have a Consent managed by the customer
  1. <Delete Consent Record>: This command lets the user delete a consent record of the mobile number from the database. You should be very careful using this command and it is recommended that you only invoke this command if an end-user has revoked their consent by either sending a request to you, changes carriers or send an Opt-out request via a MO message using any of the Opt-out keywords below in the Opt-out/Consent revoke section.

 

Please note that US regulations under TCPA also mandates other forms of opt-out including via email, verbally or in-person.

Sample Request

curl -X DELETE -H "Authorization: Bearer d17f79e76e30d7a0f05e65589b0bbc78a" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses /Q6xviejOT23ew0X5Yf6Fp4

where:

Customer should perform a GET to List the consent status result of which will give them the consent status ID they will need to delete a record from the database

 

OPT-OUT/Consent Revoke

The Syniverse Managed Consent support the revoking of consent by users or as mandated by the messaging campaign approved by the US carriers.

End-users can revoke a consent by Opting out of a Program associated with a shortcode. The most common form of Opt-out is by the end-user sending a STOP keyword to a Shortcode. There are other keywords that are supported as Opt-out Keywords:

  • End
  • Cancel
  • Unsubscribe
  • Quit
  • STOP ALL

The Syniverse Managed consent automatically processes SMS MO Opt-out keywords and notify the Customer via MO callback event.

End-users can also request to Opt-out of a program by contacting the Customer via email, POS or by telephone. Customers are obligated to process this request by invoking an Opt-out process.

 

Opt-out /Consent Revoke by Customer Notification

<Contact Opt-out via API> : Customers can invoke the contact Opt-out API to revoke consent for a subscriber that is in the consent management database. This use case is typically performed when a subscriber contacts the Customer via POS, website, email or any other approved channel besides sending a SMS MO opt-out keyword.

Sample Request: Customer Triggered Opt-Out

curl -X POST -H "Authorization: Bearer d17f79e76e30d7a0f05e6558922bbc78a " -H "Content-Type: application/json" -d '{"sender_id":"51RLyL2S2wZGBuTrXri4E1","addresses":["+14085551212","+18135551212"]}' https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses/optout

where:

A consent status event will be “Posted” back to the customer via the Sender ID event topic.

For all other Opt-out methods, Customer needs to invoke the “Delete Consent Record” API to remove the user’s record from the consent database. Customer should perform a GET to “List” the consent statuses of end-users in their program, result of which will give them the consent status ID associated with a particular phone number they will need to delete a record from the database

All subsequent messages to a Mobile number associated with your Shortcode that has a consent status value of Opt-out will be rejected with a failure response “No Consent”

 

 

Subscriber Consent Discovery Channel attribute

The Subscriber Consent Discovery Channel attribute allows customers to specify which channel a particular end-user opts in/gave initial consent from (discovers your program) . The discovery channel attributes are:

  • Opt_in_type
  • Opt_out_type

 Opt-in/Opt-out type value can be of:

  1. web
  2. IVR
  3. app
  4. email
  5. POS
  6. Other (Default if no value is given)
  7. SMS (Value for all MO Keyword Opt-in/Opt-out)

For all the new Opt-in/opt-out type values, the information will come from the customer in all cases except for SMS opt-in and opt-out which comes directly to SCG.

SCG will process and store the values for the new attributes against the end-user records in the consent management database. Relevant events associated with the successful API call to opt-in or opt-out a particular end-user will be included in the events posted back to the customer’s application via their configured webhook.

These new attributes will be available in both the Syniverse Managed Consent service and the SCG Unsolicited Opt-out service.

Sample Solicit Consent (Opt-in) resource with Opt-in type attribute

Using the  attribute "opt_in_type” in the Solicit Consent API resource


 curl -X POST -H "Authorization: Bearer 8f8a41a5799eff1661a54e920d16f95"

-H "Content-Type: application/json" -d '{"address_type":"LONGCODE","address":"+14085551212", "opt_in_type":"web",
  "sender_id":"i7GQ7hxAxNDsIArveY5qm3"} https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses

 

  • API Endpoint: https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
  • address_type: The type of end-user address being opted in. e.g. Longcode (Regular E164 mobile number),
  • sender _id: The unique ID for the customers shortcode
  • address: The mobile number that the customer is requesting opt-in consent for (E.164)
  • opt_in_type: The discovery channel from which the end-user gave initial consent. See available values above.

Sample End-user Opt-out resource with new Opt-out Type attribute

Using the attribute “opt_out_type” in the End-user Opt-out resource

curl -X POST -H "Authorization: Bearer 8f8a41a5996eff1641a66e920d16f95" -H "Content-Type: application/json" -d '

{“sender_id”:“51RLyL2S2wYGBuTrXri4E1”,“addresses”:[“+14085551212”],“opt_out_type”:“email”}' https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses/optout

 

  • API Endpoint: https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses
  • address_type: The type of end-user address being opted in. e.g. Longcode (Regular E164 mobile number),
  • sender _id: The unique ID for the customers shortcode
  • address: The mobile number that the customer is requesting opt-in consent for (E.164)
  • opt_out_type: The discovery channel from which the end-user gave initial consent. See available values above.

 

Other resources in the GET, UPDATE and LIST API's

List consent status

curl -X GET -H "Authorization: Bearer 2d36a89c-cd98-337a-8d50-491e65f2dbb8" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses

List Consent for  a particular consentId

curl -X GET -H "Authorization: Bearer 2d36a89c-cd98-337a-8d50-491e65f2dbb8" https://api.syniverse.com/scg-external-api/api/v1/consent/contact_address_statuses/OgC142KNOldkS0o6pj3MV6

 

Sender ID Consent Event Status 

To get consent status for end-users on a particular shortcode, Customers can setup a webhook (Delivery configuration) and subscribe to the SCG-Sender-ID topic.

The SCG-Sender-ID topic has the event “sender_id_recipient_consent_change”. This event contains the change in consent status of a particular recipient.

How to setup and subscribe to the SCG-Sender-ID topic

Delivery Configuration (webhook) setup:

  • Select Events Manager from the SDC portal and click on Delivery Configuration
  • Click on New Delivery Configuration
  • Complete the configuration setup by adding your configuration name, callback URL (Address) and click Create to complete the delivery configuration setup

Subscribe to SCG-Sender-ID Topic

  • Navigate to Events Manager and select Subscriptions
  • Click on New Subscription
  • Complete the Subscription form by selecting "SCG-Sender" from the Topic field
  • In the Event Type, the default is "all types" but you can select specific events in the Event Type field. 
  • Select your Delivery configuration from the drop down
  • Select a start date and an end date if so desired. End dates/time are not mandatory
  • Select Create to complete subscription setup

 Sample

{"topic":"SCG-Sender-ID","attempt":1,"event":{"fld-val-list":{"company-id":9002,"sender_id_id":"yKTJEeK90YX01O69ighea1","consent_status":"OPTIN","recipient_address":"+14085551212","application_id":106},"evt-tp":"sender_id_recipient_consent_change","timestamp":"2018-02-23T20:36:04.97Z"},"event-id":"eImNljiSQUyz4b0gFZkfKg"}
{"topic":"SCG-Sender-ID","attempt":1,"event":{"fld-val-list":{"company-id":9002,"sender_id_id":"yKTJEeK90YX01O69ihsea1","consent_status":"OPTOUT","recipient_address":"+14085551212","application_id":106},"evt-tp":"sender_id_recipient_consent_change","timestamp":"2018-02-23T20:38:41.004Z"},"event-id":"tMS4eJK9Q7O6o6npRTRXXw"}

 

 

The event “sender_id_recipient_consent_change” contains the change in consent status of a particular recipient/end-user

Sample consent status events

{"topic":"SCG-Sender-ID","attempt":1,"event":{"fld-val-list":{"company-id":9002,"sender_id_id":"yKTJEeK90YX89O69ighea1","consent_status":"OPTIN", “opt_in_type”:“web”, "recipient_address":"+14085551212","application_id":106},"evt-tp":"sender_id_recipient_consent_change","timestamp":"2018-02-23T20:36:04.97Z"},"event-id":"eImNljiSQUyz4b0gFZkfKg"}
{"topic":"SCG-Sender-ID","attempt":1,"event":{"fld-val-list":{"company-id":9002,"sender_id_id":"yKTJEeK90YX89O69ihsea1","consent_status":"OPTOUT",“opt_out_type”:“ SMS”,"recipient_address":"+14085551212","application_id":106},"evt-tp":"sender_id_recipient_consent_change","timestamp":"2018-02-23T20:38:41.004Z"},"event-id":"tMS4eJK9Q7O6o6npRTRXXw"}

 

 

 

Was this article helpful?
1 out of 1 found this helpful

0 Comments

Please sign in to leave a comment.