Messaging

The Octy messaging API utilizes the most basic but robust form of natural language generation using message content templates. Creating message templates allows you to generate personalized messages at scale in seconds.

Create message templates

Message templates can be created by making a request to the v1/retention/messaging/templates/create endpoint.

A maximum of 100 templates can be created in a batch with any single request to the v1/retention/messaging/templates/create endpoint.


When creating message templates you must provide:


  • • a friendly name - (to be used as a template identifier)
  • • a message type - (this can be anything you want, for example, email or social advertisement)
  • • a title - (you can think of this as a subject line)
  • • content - (this contains the dynamic value placeholder tags)

Example : "Hi {first_name}, we have some great deals for our {customer_type} customers"


  • • any required data parameters and default values.

Placeholder tags

Placeholder tag - a short descriptive string, with a limited number of words, separated by underscores "_" or dashes "-", that accurately represents the inferred value.


Placeholder tags are identified in a template's content attribute by wrapping them within curly brackets {}. Example: {placeholder_tag_example}, in addition to explicitly specifying them within the required_data parameter of a create template request.


Each placeholder tag, defined within the required_data parameter, must be supplied with a default value, to allow for any missing data when generating content for said template.


Example: first_name : "There". Now if the value for the first_name parameter is not provided when generating content, the default value "There" will be populated within the specified message content for this request. See Template content example below; when populated with data or default values, the content of this template would produce one of the strings shown below.


Example: Template content (with dynamic/default values)

Template : "Hi {first_name}, we have some great deals for our {customer_type} customers."


Using dynamic provided data: "Hi Ben, we have some great deals for our gold customers."


Using default values: "Hi There, we have some great deals for our favorite customers."


In addition to dynamic values, item recommendations can be automatically populated into a specific profile's message content. To accomplish this, {ITEM_REC} placeholder tags should be specified within the template's content parameter as required.

Please note, default values can NOT be set for {ITEM_REC} placeholder tags.

Example: Template content (with item recommendations)

Template : "Hi {first_name}, we think you might like this {ITEM_REC}."


Using item recommendations: "Hi Ben, we think you might like this T-shirt."



Rules for working with message templates containing an ITEM_REC placeholder tag:


  • • If Item recommendations can not be made for the provided profiles_id(s), message generation will fail.
  • • If your account has no existing trained-recommendations-model, then any attempt to generate message content for templates that contain ITEM_REC placeholder tag(s) will fail and an error will be returned.

Generate content

Message content can be generated by making a request to the /v1/retention/messaging/content/generate endpoint.

A maximum of 100 messages can be generated in a batch, with any single request to the /v1/retention/messaging/content/generate endpoint.


You have the option to supply data in order to generate the templates content. To do this, you simply specify key : value pairs within the data parameter of each message object of the content generation request.


  • • The key represents the name of the required_data attribute/placeholder tag for the template.
  • • The value represents the desired values used to replace the placeholder tags and populate message templates.

The template_id should be supplied within each message-object, within the messages-parameter of the generate-content-request to specify the template that should be used to generate the content of each message. The template_id specifies which template will be used to generate the content of each message.

Example:

"messages" : [
    {
    "template_id" : "template_75869768...",
    "item_recommendation" : false,
    "data" : [ 	
               { 	
                 "first_name" : "Ben",
                  ... other parameters required for specified template 
               },
               { 	
                 "first_name" : "Saleena",
                  ... other parameters required for specified template 
               }
             ]
    },
    {
    "template_id" : "template_22b25c07...",
    "data" : [ 	
               { 	
                 "first_name" : "Jamie",
                  ... other parameters required for specified template 
               },
               { 	
                 "first_name" : "Brendan",
                  ... other parameters required for specified template 
               }
            ]
    }
]

Referencing the above request body example, the body of the response would contain four message objects; the first two would generate message content for “Ben” and “Saleena” using the template “template_75869768...” and the second two would generate message content for “Jamie” and “Brendan” using the template "template_22b25c07..."


If you wish to generate messages with item recommendations, you should follow the guidelines outlined below:


  • • your template must contain at least one ITEM_REC placeholder tag.
  • • you must specify 2 things with the parameters of the request:
    • 1. the item_recommendation parameter must be set to "true".
    • 2. You must provide a valid profile_id key : pair with each message object nested within the data parameter.

      where key = profile_id and value = a valid Octy generated profile identifier

      Example :

      "messages" : [
          {
          "template_id" : "template_0309849303...",
          "item_recommendation" : true,
          "data" : [ 	
                     { 	
                       "first_name" : "Ben",
                        ... other parameters required for specified template 
                        "profile_id" : "profile_8c2678ee5abaf76105eef5" 						      
                     },
                     { 	
                       "first_name" : "Saleena",
                        ... other parameters required for specified template 
                        "profile_id" : "profile_ea0a534f5be61405636882" 						      
                     }
                  ]
          }
      ]
      

If your desired message template does NOT contain ITEM_REC placeholder tags, the item_recommendation parameter must be set to "false" for that message-object, within the messages-parameter.



Next steps

Finally, you will explore how the Octy recommender system can be implemented into multiple layers of your system.

Go to the Recommendations section of this documentation to learn more about how item recommendations work.