Unsubscribe Mobile Numbers at Keyword Level in MobileConnect Using Salesforce Marketing Cloud REST API

Author: Florin Valean

Use case

This solution can be useful when we need to allow customers to opt out of a specific keyword in MobileConnect. A common scenario would be when a customer is subscribed to multiple keywords associated with a short code and they want to unsubscribe from one of the keywords - this is currently not possible with the standard functionality in MobileConnect therefore a custom solution needs to be implemented and this is described in this post.

We will need Marketing Cloud Rest API for this - contacts/v1/contacts

/* replace YOUR_SUBDOMAIN with your subdomain generated when you create the Installed Package in Marketing Cloud */ https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/contacts/v1/contacts


For this use case we are going to use an Installed Package created with enhanced functionality with a component of type API Integration and integration of type Server-to-Server. Make sure you assign all the scopes you need to the Installed Package.

We also need to create a Mobile Opt-In message in MobileConnect. See this page for more details.

OAuth 2.0 access token is required. For more details on how to obtain and how to use the access token go to this page.

The payload for /contacts/v1/contacts is in JSON format and it will look like this:

/* replace the ContactKey, Keyword and Mobile Number with your own values ContactID can also be used instead of ContactKey Keyword here is the Keyword ID that can be found in the _SMSMessageTracking data view */ { "contactKey":"1234", "attributeSets": [{ "name":"MobileConnect Subscriptions", "items": [{ "values": [ { "name":"Keyword", "value":"ZEN76D93-B848-4C4D-9325-7F9CE5DF1799" }, { "name":"Mobile Number", "value":"44123456789" }, { "name":"Opt In Status", "value":0 }, { "name":"Opt Out Status", "value":1 } ] }] }] }

Server-side javascript sample code

You can create a landing page in Web Studio and include this code. Publish the page and load it in a web browser to test the code.
This server-side javascript code uses Marketing Cloud REST API. It will make a HTTP Patch call to contacts/v1/contacts for a partial update on the MobileConnect Subscriptions data extensions. The fields that we are going to update are Opt In Status and Opt Out Status.

/* replace the highlighted values with yours */ <script runat="server"> Platform.Load("Core", "1.1.1"); try { /* get OAuth 2.0 access token */ var payload = '{"grant_type":"client_credentials",'; payload += '"client_id":"d20aaul96htb2hgo9b4i47gx",'; payload += '"client_secret":"tUriuDS0zdV82vFrLIbJek77",'; payload += '"scope":"list_and_subscribers_read list_and_subscribers_write",'; payload += '"account_id":"012345678"}'; var OAuth2URL = "https://mc06n741d3km57h-ztlmx29hh3s7.auth.marketingcloudapis.com/v2/token"; var contentType = 'application/json'; var accessTokenResult = HTTP.Post(OAuth2URL, contentType, payload); var tokenObj = Platform.Function.ParseJSON(accessTokenResult["Response"][0]); var accessToken = tokenObj.access_token; var auth = ["Bearer " + accessToken]; /* create the payload */ var payload = { "contactKey":"1234", "attributeSets": [{ "name":"MobileConnect Subscriptions", "items": [{ "values": [ { "name":"Keyword", "value":"ZEN76D93-B848-4C4D-9325-7F9CE5DF1799" }, { "name":"Mobile Number", "value":"44123456789" }, { "name":"Opt In Status", "value":0 }, { "name":"Opt Out Status", "value":1 } ] }] }] }; /* make the API call and get the response */ var contactsUrl = "https://mc06n741d3km57h-ztlmx29hh3s7.rest.marketingcloudapis.com/contacts/v1/contacts"; var req = new Script.Util.HttpRequest(contactsUrl); req.emptyContentHandling = 0; req.retries = 2; req.continueOnError = true; req.contentType = "application/json"; req.setHeader("Authorization", auth); req.method = "PATCH"; req.postData = Stringify(payload); var response = req.send(); Write(Stringify(response)); } catch(e) { Write(Stringify(e)); } </script>

Notice the use of try-catch block - see this page for more details on how/when to use try-catch.

Script outcome in MobileConnect

As a result the Opt In Status and Opt Out Status attributes in MobileConnect Subscriptions data extension will be updated with the specified values.

Share this page
Stay in touch

Subscribe to the newsletter

p1 p2 p3