Keyword Forwarding

When an SMS message is received using a specific keyword, you can post the message, along with the mobile number and short code, to an externally hosted web service for further processing. See the User Help Center for more information.

This topic explains more in-depth from the developer side.

Configuration

  1. Every keyword defined for an account has an option called Keyword Forwarding. This is part of the account admin's Short Code Keyword Management view (in RI: Account tab from the left top dropdown menu, select Short Code Key Management link from the lower part of the Account Admin page):

  2. If an account admin wants to forward a message, check this flag to TRUE for a specific keyword. In the above example, the “PAY” keyword will have this flag set to true.
    1. Note that in RI, the keyword must be one word. i.e. “PAY FULL” will not work, however “PAYFULL” will.
  3. In addition to the above, the account admin should create a partner to setup the end point.
    1. Client will provide an HTTP endpoint along with username / password for user authentication.
      1. An SSL certificate for the URL will also be needed to send to RI if an HTTPS endpoint is required.
    2. Once this information is provided, Responsys Ops will configure this in the back end as a one-time setup for the account.
    3. Note only one endpoint can be setup per RI Account.
  1. Note that this POST process will have a configured number of time-outs and retries as part of the Responsys gateway server configuration. The system doesn’t wait for a “successfully received” ACK-back. Once the configured number of retries are exhausted, the system logs a failed event and moves on.

Forwarding MO HTTP POST Structure

When an end-user sends in an MO with a keyword, the RI system will use the configured client endpoint to send the message forward. The following data are sent through as POST parameters

  • Mobile code - Long/Short code
  • Keyword
  • Mobile Number - in E.164 format
  • Message - The entire contents of the message

The client system will receive this data and continue with internal business logic/processing.

Sequence of Events

The Responsys system logs the following events as part of this feature:

  • SMS Received event - When we receive an MO from a mobile user through an aggregator
  • SMS MOFWD Sent event - When we send/forward the MO to the pre-configured end-point
  • SMS MOFWD Failed event - When the message could not be sent to the pre-configured end-point (after exhausting all retries)

Upon receipt at the SMS Received Event Program object, the incoming MO is first sent to the pre-configured endpoint via HTTP GET, and then continues with the regular RI SMS Received Event processing as part of the Program. The MO processor checks whether the incoming number exists in the system and if not, adds that number to the Contact list and sends that RIID to the program for further event processing.

Example: Customer-initiated MO Keyword Response (Keyword “CREDIT”)

Requirement:

  • Line of Credit Available Credit Inquiry
    • Short code: 11111
    • Keyword “CREDIT”
    • Response: “You currently have <available_credit> available on your line of credit, #<loan_id>. Log on to our website and click REQUEST ADVANCE to take a new draw.”

RIv6.27 Message Flow:

RIv6.27 Implementation:

  • RI Keyword Forwarding Program
    • Keyword CREDIT will have already been defined as in the first section of this document.
    • Routes the incoming message to the client endpoint as HTTP Post, e.g.
      • Mobile code: 11111
      • Keyword : CREDIT
      • Mobile Number - in E.164 format
      • Message - <none>
  • Upon receipt at client endpoint:
    • Parse the incoming detail
    • Execute required authentication & validation.
    • Prepare response.
    • Send API call: mergeTriggerSMS (refer to Standard API Guide- Standard for detail):
      • Syntax:
      • TriggerResult[] = service.mergeTriggerSMS(RecordData recordData, ListMergeRule mergeRule, InteractObject campaign, TriggerData[] triggerData)
      • Usage: Use the mergeTriggerSMS function to merge member(s) into the profile list and subsequently trigger SMS message(s) to the merged member(s) in a single call.
      • Request Arguments:

      Name

      Type

      Description

      recordData

      RecordData

      Array of RecordData objects that contain field and record data, e.g. MOBILE_NUMBER_

      mergeRule

      ListMergeRule

      Defines merge rules for how to handle the record data, e.g. insert / update, etc.

      campaign

      InteractObject

      Campaign name and folder, e.g. CREDIT_response, z_MobileMigration

      triggerData

      TriggerData[]

      An array of TriggerData objects that consists of any OptionalData object array. E.g. personalization parameter or complete strings.

  • API Trigger Campaign
    • Create new SMS Campaign -> Direct API Notifications
      • E.g CREDIT_response, stored in folder z_MobileMigration
    • The API call will trigger the configured message in this campaign. There are two options for message configuration, particularly for personalized messages, e.g. with customer-specific details such as Loan ID:
      • Client supplies the entire message in OptionalData object array of the API call
        • The entire message, including template wording as well as customer-specific information, e.g.:
        • You currently have $500.00 available on your line of credit, # 12345. Log on to our website and click REQUEST ADVANCE to take a new draw.
        • The Direct API Notification campaign simply has a dynamic variable defined to populate the entire string as received.
      • Client supplies customer-specific detail in individual variables
        • The API call will include the following in OptionalData object, e.g.
          • available_credit, 500
          • loan_id, 12345
        • The Direct API Notification campaign will have dynamic variables that will be populated with the incoming values:
        • You currently have $<available_credit> available on your line of credit, # <loan_id>. Log on to our website and click REQUEST ADVANCE to take a new draw.

MT Triggered Operational Notifications

These types of campaigns are initiated from the client side via API call (mergeTriggerSMS), similarly to the above MO response Direct API campaigns. They differ in that the MT triggered notifications might be a batch campaign such that more than one recipient might be included in the recordData component of the call. The API can handle up to 200 records in a single API call.

Learn more

SMS MO Forwarding Feature Setup