Using Templates in SCG

Avatar
Kola Layokun
Follow

One of the features marketers and developers can expect to see on the Syniverse Communication Gateway is the ability to create and use templates to compose SMS messages used to interact with end-users.

Templates provides the ease of composing messages especially if the business wants to send the same message content to multiple users.

Public Templates

SCG provides sample templates that customers can use out of the box. We call this Public templates. This are pre-defined templates for specific but commonly seen use cases for engaging end-user via SMS.

Below are a list of public templates available on the platform:

  • Public shipping alerts
  • Public SMFA- Requires Sniverse Multi-factor Authentication service
  • Public Password reset
  • Public Appointment notification
  • Public Flight alerts
  • Public Delivery alerts
  • Public Pickup alerts

mceclip0.png

 

Private Templates

Users can also create their own templates and customize it for use with their message deliver.  Users can create a template via the UI console or via API.

Via UI Console

  • Navigate to the Template menu on the left nav bar in the Messaging console and select "Template"
  • Click on mceclip1.png to create new template using the $ and curly brackets to designate your variables e.g ${name}create_template.png
  • Click save to same your template

Via API

Create Template
curl -X POST -H "Authorization: Bearer Token" -H "Content-Type: application/json" -d '{"designation":"TEMPLATE","name":"Kolanator_Alerts","pattern":"Dear ${Customer_name}, this is to inform you that your order ${Order_number} has shipped. Thank you"}' 
https://api.syniverse.com/scg-external-api/api/v1/messaging/message_templates 

 

Send a Message using a Template

Users can send a message with a template once its been created or they can use a public template if so desired. 

Send a message using a template via the Message Console

  • In the Send Message menu, populate the "From" and "To" fields as desired
  • Select your desired template by clicking the drop down button in the "Template" field
  • Complete the information in the Template variables fields of your templateSend_template.png
  • View the "Message Result"  to verify your message
  • Click "Send" to submit the message for delivery.

 

Send a message using a template via the API

curl -X POST -H "Authorization: Bearer Token" -H "Content-Type: application/json" -d '{"from":"OfX4r7DeQrh7HXXHyqb5m5","to":"+14085551212","body":"#set($customer_name=\"Kolanator\")\n#set($Ref_Number=\"12344TP\")\n#set($link=\"http://www.kolanator.com\")\n#parse(\"Shipping_Alert\")"}' https://api.syniverse.com/scg-external-api/api/v1/messaging/messages

 

Variable Definition in Message Templates

Message templates allow variable placeholders that will get replaced with value parameters specified on the message request using a template for sending a message. Within a template pattern, the variable placeholders should be defined in the following format: ${variable_name}. 

Note : Variable names are case sensitive. Multiple variables can be defined in a template.

For example : The following template pattern defines variable placeholders like CustomerName, BrandName, OrderNumber and OrderLink which can be replaced with actual values when the message is being sent.

Template Name : "Shipping_Alert"

Template Definition : "Dear ${CustomerName}, this is to inform you that your order ${OrderNumber} has been shipped. Click on the link ${OrderLink} for order status. Thank you for being a valuable customer of ${BrandName}".Text STOP to end subscription to shipping alerts via SMS.

 

Variable Substitution in Message Request Payload

When submitting the API request, the following are valid ways to submit variable parameter values. Single quotes can be used to enclose the variable values for substitution.

Template Name : "Shipping_Alert"

Template Definition : "Dear ${CustomerName}, this is to inform you that your order ${OrderNumber} has been shipped. Click on the link ${OrderLink} for order status. Thank you for being a valuable customer of ${BrandName}".Text STOP to end subscription to shipping alerts via SMS.

Template variables values :

Message Request Payload for Message Body

"body":"#set($CustomerName='John Doe')#set($BrandName='Syniverse Technologies')#set($OrderNumber='999999999')#set($OrderLink='http://developer.syniverse.com/order/999999999')#parse('Shipping_Alert’)”

If one of your variable requires a dollar sign and dollar sign is used to designate variables, you can either pass that dollar sign in the message body within the variable value parameter or you can precede the variable definition in the template pattern like $${amount}.

If single quotes are part of the variable value being substituted (Example : John D'Silva), then non-escaped single quotes within the variable values are also allowed as shown below. Also escaped double quotes can be used for specifying variable values.  

Message Request Payload for Message Body (escaped single quotes in variable value)

"body":"#set($CustomerName='John D'Silva')#set($BrandName='Syniverse Technologies')#set($OrderNumber='999999999')#set($OrderLink='http://developer.syniverse.com/order/999999999')#parse('Shipping_Alert’)”

Message Request Payload for Message Body (escaped double quotes)

"body":"#set($CustomerName=\"John D'Silva\")#set($BrandName=\"Syniverse Technologies\")#set($OrderNumber=\"999999999\")#set($OrderLink=\"http://developer.syniverse.com/order/999999999\")#parse('Shipping_Alert’)”

Based on the message request payload specified above the message text will be constructed as :

"text":"Dear John D'Silva, this is to inform you that your order 999999999 has been shipped. Click on the link : http://developer.syniverse.com/order/999999999 for order status. Thank you for being a valuable customer of Syniverse Technologies. Text STOP to end subscription to shipping alerts via SMS.

New lines are allowed between each #set, #track and #parse statement but are not required. 

"body":"#set($CustomerName='John Doe's')\n#set($BrandName='Syniverse Technologies')\n#set($OrderNumber='999999999')\n#set($OrderLink='http://developer.syniverse.com/order/999999999')\n#parse('Shipping_Alert’)”

If a variable value #set parameter is not supplied in the message request payload, then message text will be constructed with the variable name as shown below :

Template Name : Welcome template

Template Definition :  "Hello ${name}.  Call us at 1-800-888-888 for any questions."

Message Request Payload for Message Body : "body":"#parse(‘Welcome template’)”

"text" :  "Hello ${name}.  Call us at 1-800-888-888 for any questions." 

 

Use of Contact Attributes as Variables in Message Templates 

When a contact is specified in the "to" field of the message request, contact attributes can be used as variable values for substitution in message template variables.   

  • To use the Contact object, you would define the variable in the template pattern as ${Contact.field_name} where field_name is a valid attribute of a contact. 
  • Validate attributes are:
      • first_name
      • last_name
      • birth_date
      • first_acquisition_date
      • last_acquisition_date
      • primary_mdn
      • primary_addr_line1
      • primary_addr_line2
      • primary_addr_city
      • primary_addr_zip
      • primary_addr_state
      • primary_country
      • primary_email_addr

 

Public API to validate template definition and variable substitution

A new API has been added to validate template definitions with the variable setting patterns used to send a message. 

  • End point : https://api.syniverse.com/scg-external-api/api/ v1/messaging/template/validate
  • The input for this end point is like the payload for submitting a message request using template and variables, so a Sender Address and Recipient must be provided as inputs.
  • If the validation is successful, then the message text will be returned as response which will look exactly like the message text that would be delivered to the device.
  • If an error occurs in the parsing of the template pattern specified, parsing or substitution of the variable values, then an error message will be returned message along with HTTP status code of 400.  

Sample Usage of API

Template Definition: ${Brand_name}: ${free_form_text}. For more information click ${link}. Text STOP to unsubscribe from alerts.

API Request :

 {
      "from“ : "address:99999",
      "to“ : "+15555555555",
      "body“ : "#set($Brand_name='Syniverse Technologies')#set($free_form_text=‘New template validation API is available!’)#set($link='http://developer.syniverse.com')#parse(‘Public_Alert’)”
 }

API Response :

 {
      "text“ : "Syniverse Technologies: New template validation API is available! For more information click on the link   http://developer.syniverse.com. Text STOP to unsubscribe from alerts."
 }

Chinese Template Example

Template Definition : 提醒：您的航班 ${ABC}從门${DEF} 起飛至 ${LAS}。文本停結束

API Request :

{
     "from“ : "address:99999",
     "to“ : "+15555555555",
     "body“:set($ABC='Apples')\n#set($=DEF'Dolphins')\n#set($LAS='Lasers')#parse('TEST_CHINESE_1')"
  }

API Response :

  {
       "text": "提醒：您的航班 Apples從门Dolphins 起飛至 Lasers。文本停結束"  

  }

Dollar Sign Example

Template Definition : Hello. Your remaining balance in your account is $${amount}. Check your account for more details.

API Request :

{
     "from“ : "address:99999",
     "to“ : "+15555555555",
     "body":"#set($amount='100.00')#parse('Donation template’)”

}

API Response :

{
   "text": "Hello. Your remaining balance in your account is $100.00. Check your account for more details." 

}

Contact Object Example

Template Definition : Your message is $TEST ${Contact.first_name} #track("http://www.google.com")

API Request :

  {
     "from“ : "address:99999",
     "to“ : "contact:dXTt37FhVbQK52NFvxpj42",
     "body“ : "#parse('withparams’)”

  }

API Response :

  {
      "text": "Your message is $TEST Steven https://2lnkme.net/zWcssD" 

  }

Note : This example also shows the use of the #track keyword to create a link that will track if a recipient clicks the link. Also the $TEST variable is an invalid variable definition, so it is not affecting the template processing and variable substitution.

 

Template Validation via SCG Console

Send Message in the SCG console (under each message type tab - SMS, MMS, RCS, etc...) provides the ability to send a message using templates.  Populating all the inputs for sending a message provides a simulated message result text string.

A new Validate Template button has been added to help validate the template patterns with variable substitution. Clicking the button will validate the message request payload using the new template processor , parse the template pattern and populate the variable values with the supplied parameters to form the message body. 

The Validate Template button will turn green if there were no errors in the parsing of the template pattern and the variable parameter substitution. 

The Validate Template button will turn red if there is an error and the error reason will be displayed in the "Validated/Actual Message Result" field on the screen. 

mceclip0.png

 

mceclip1.png

mceclip2.png

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

0 Comments

Article is closed for comments.