How to trigger actions based on Keywords

 

 

The basic function of SCG Keywords is to implement “autoreply” messages. These autoreplies are triggered when a sender_Id number gets a MO message from a consumer device, when the message contains the KEY value in its message body, SCG sends the predefined message as a reply to the consumer number. This functionality can be setup in the SCG UI.

Find details on how to create a Keyword here.

There are use cases were the enterprise needs to do actions or processing when the event of a Keyword happens. An example of this could be the need of an autoreply and provide support to a customer that send the message "help". In this use case, the enterprise could setup a Keyword that sends an autoreply to the consumer indicating that a local representative will contact him soon and start a process to have a representative to contact the customer that requested help.

In addition to the SCG Keywords that setup the autoreply, there is an action that needs to be performed in the enterprise system. To start this processing a callback is needed.

Syniverse Event Subscription Service (ESS) provides a topic (SCG-Keyword)  and subscription (keyword_message_received) that allow the implementation of webhooks when a Keyword event occurs (arrival of an MO with the keyword configured value). This allows to take additional actions (in customer side systems) on the arrival of and MO with the keyword value.

 

Subscription example

In our example, let's say we have a SCG-Keyword with the ID "0hB7yYxdKUmaBizPncQvj" that sends the autoreply message to the consumer when the consumer sends the "help" message (MO).

In addition, we can create a Subscription to send a callback to a webhook to signal the occurrence of the event for the enterprise to start processing it.

To create the Keyword subscription:

• Login in SDC at https://developer.syniverse.com/home.html
• Select the option Event Manager / Subscriptions

 

• Click the "New Subscription" button:

 

• Select SCG-Keyword as Topic from the list:

 

• Select keyword_message_received Event Type from the list:

 

• Select your preferred Delivery Configuration:

 

• Set the Matching Criteria to link your "help" Keyword by keyword_id in this example id 0hB7yYxdKUmaBizPncQvj:

 

• Click the Create button.

After you create the described subscription, your webhook server will start receiving event notifications (callbacks).

 

Example Callback (webhook)

As result, in the event of an MO message with the "help" keyword, an autoreply message will be sent and additionally, the related webhook will get a callback like the above:

{
  "topic": "SCG-Keyword",
  "attempt": 1,
  "event": {
    "fld-val-list": {
      "associated_info": "",
      "company-id": XXXXXX,
      "keyword_id": "0hB7yYxdKUmaBizPncQvj",
      "sender_id_id": "wtdyzez0n3chq4oXXXXXX",
      "keyword_campaign_id": "",
      "keyword_value": ".*help.*",
      "recipient_address": "+5066173XXXX",
      "keyword_action": "STORE",
      "application_id": XXXXX,
      "reply_sent": true
    },
    "evt-tp": "keyword_message_received",
    "timestamp": "2024-10-09T19:10:37.351Z"
    },
  "event-id": "3ko2VWZzR-iMXals16voJw"
}