docs.octy.ai

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 500 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 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 double curly brackets {{}}. Example: {{placeholder_tag_example}}

Each placeholder tag, defined within the content parameter, must be supplied with a default value, to allow for any missing data when generating content for said template. Default values can be plain text, HTML or anything else that can be parsed as a string.

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 favourite 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 with a specific item attribute as required.

Example: Template content (with item recommendations)

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

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

In this example the template engine retrieved the specified profiles top item recommendation and replaced the {{item_rec.item_name}} placeholder tag with said item’s name value.

Allowed recommended item attributes:

item_id

item_name

item_description

item_price

item_category

💡

Note: Any placeholder tag that contains a period character “.” will be processed by Octy AI as an item_rec placeholder tag. None item_rec placeholder tags that contain periods will result in validation errors being thrown when generating content.

Metadata

Metadata is useful for storing additional, structured information on a message template object. For example, you could store the churn probability label this template applies to e.g: churn_pred: “high”. This metatag could then be used in your systems to automatically identify which message template to use when generating dynamic personalized content for a customer that has a “high” churn probability. Any supplied template metadata is not used by Octy.

🖥️ CLI


octy-cli apply --filepath {path/to/message-template-definitions.yml}

Example message-template-definitions.yml :


kind: templates
templateDefinitions:
    - friendlyName: Basic personalised greeting
      templateType: email
      title : We have some great deals for you!
      content : Hi {{first_name}}, we have some great deals for you {{greeting}}!
      defaultValues:
        first_name: there
        greeting : my friend
      templateID : template_1234 # As template ID is supplied, cli will attempt to update this template

    - friendlyName: Website heading banner
      templateType: website
      title : --
      content : Wait! before you think about going...
      defaultValues:
      metadata: # show this banner to customers that have a high churn probability and a high RFM score, i.e your best customers that are likely to churn
        churn_pred : high
        rfm_score_upper : 444
        rfm_score_lower : 333

Generate content

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

A maximum of 500 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 placeholder tag in the templates content parameter.

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.

Example:


"messages" : [
    {
    "template_id" : "template_75869768...",
    "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" : "Alan",
                  ... 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 Alan using the template "template_22b25c07..."

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

Your template must have pre specified item_rec placeholders tag(s) each with a single corresponding allowed item attributes. Eg. {{item_rec.item_name}} or {{item_rec.item_price}}

The value provided for any item_rec placeholder tag must be a valid Octy AI generated profile identifier profile_id. Example:


"item_rec.item_name" : "profile_xxx"

The exception to the second rule is if the item_rec item attribute is item_price. In this case the value provided for this parameter must have the following syntax →


"item_rec.item_price" : "profile_id::currency_from::currency_to::discount"

where each value is separated by a double colon ::, follows the specified order and :

profile_id is a valid Octy AI generated profile identifier

currency_from is a currency code that represents the base currency your items prices are based on.

currency_to is a currency code that represents the currency the item’s price should be converted too from the currency specified in the currency_from parameter of this data object.

💡

Note: if the currency_from and currency_to values are identical, the system will simply return the item price in the currency specified in the currency_from parameter.

Octy AI pulls currency rate data from this provider to enable currency conversions for recommended item prices.

discount represents a percentage that should be discounted from the item’s price. For example, providing the value 40 here would discount the item’s price by 40%. Note that the value provided for the discount parameter must be and number between 0 and 90

If multiple item_rec placeholder tags are supplied in any single message data object, the provided profile_id(s) for each must match. Each message data object should be considered as content that is being generated for a single person or entity.

Duplicate profile_ids should not be provided inside any message object outside of the scope of any single data object.

Rybbon integration - Reward cards

Octy AI and Rybbon (https://www.rybbon.net/) have formed a partnership to enable our users to embed Rybbon reward cards directly into message content via our API.

Reward cards boost customer loyalty and are a great way to re engage potentially churning customers.

💡

Note: To make use of this feature, you will have to first create a free Rybbon account and pre load your account balance with a desired amount. → https://app.rybbon.net/public/signup?plan=ondemand

Use cases

Churn prevention email campaign

Using a combination of Octy AI and Rybbon, your systems will be able to filter your top customers whose behaviour indicates they are likely to churn and push them onto an email campaign where Rybbon reward cards are offered as a retention mechanism.

Dynamic website content

Using a combination of Octy AI and Rybbon, your systems will be able to identify, in real-time, customers that are likely to churn and showcase dynamic bespoke content on each web page including embedded Rybbon reward cards.

Implementation

Rybbon reward cards can be added to any Octy AI message template by adding a Rybbon reward card placeholder tag {{rybbon_reward_card}} in a templates content parameter.

Example “Email” Octy AI template with a Rybbon reward card placeholder tag:


{
	"template_id": "template_xxx",
	"friendly_name": "Rybbon gift card campaign xxx",
	"template_type": "email",
	"title": "Before you go...",
	"content": "Hi {{ name }}, we want to offer you a gift card! {{ rybbon_reward_card }}",
	"default_values": {
		"name": "Friend",
		"rybbon_reward_card" : "<a href='https://www.company.xyz/rewards'>Our rewards!</a>"
	},
	"metadata": {},
	"created_at": "Sun, 12 Mar 2022 14:14:07 GMT",
	"updated_at": "Tue, 14 Mar 2022 16:10:02 GMT"
}

When generating content using a template that contains a {{rybbon_reward_card}} placeholder tag, the value provided for this parameter must have the following syntax →


"rybbon_reward_card" : "customer_id::rybbon_campaign_key::value"

where each value is separated by a double colon ::, follows the specified order and :

customer_id is a user supplied identifier representing a customer.

rybbon_campaign_key is the unique key of the campaign. Campaign must be created via Rybbon website before adding recipients via API. Once campaign is created, your key will be available on the setup tab of the campaign. Please refer to Rybbon API docs for more on this → https://demo.rybbon.net/public/v2/reference#operation/Add Reward Claim

value is a floating point number greater than 0 that represents the value that should be added on to this customers reward card. If this value exceeds the allowed value for this reward card, Octy AI will return the default value set for this {{rybbon_reward_card}} placeholder tag.

Example content generation response with a template containing a {{rybbon_reward_card}} placeholder tag.


{
	"request_meta": {
		"request_status": "Success",
		"message": "Successfully generated content",
		"count": 1
	},
	"generated_messages": [
		{
			"template_id": "template_xxx",
			"friendly_name": "Rybbon gift card campaign xxx",
			"title": "Before you go...",
			"content": "Hi Ben, we want to offer you a gift card! <table border='0px'><tr><td colspan='3' style='font-family:Verdana; color:#666666'> <b>$10.00 Best Buy® E-Gift Card</b></td></tr><tr><td> <a href='https://demo.rybbon.net/claim?claimcode={}'> <img src='https://demo.rybbon.net/public/images/reader/show-campaign-gift?campaignKey=a3e92c42a4d3e5cc18351b7480c205f9'> </a></td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign='bottom'> <a href='https://demo.rybbon.net/claim?claimcode={}'  style='color: #ffffff; background-color: #0084ff; border-radius: 5px;  text-decoration: none;padding: 5px;margin: 0;font-size: 18px;outline: none; min-width:  120px;padding-left: 10px; padding-right: 10px;text-align: center;display: inline-block;'>Get Now</a><br> <div style='font-family:Verdana;font-size:12px; color:#666666'> <a href='https://demo.rybbon.net/claim?claimcode={}'>Available</a>  until August 4, 2021</div></td></tr></table><p>"
		}
	],
	"failed_messages": [],
	"failed templates": []
}

💡

Note: {{rybbon_reward_card}} placeholder tag values are populated with HTML snippets containing all the available reward cards for the specified campaign.

Example Rybbon reward card HTML snippet:


<table border='0px'>
  <tr>
    <td colspan='3' style='font-family:Verdana; color:#666666'>
      <b>$10.00 Best Buy® E-Gift Card</b>
    </td>
  </tr>
  <tr>
    <td>
      <a href='https://demo.rybbon.net/claim?claimcode={}'>
        <img src='https://demo.rybbon.net/public/images/reader/show-campaign-gift?campaignKey=a3e92c42a4d3e5cc18351b7480c205f9'>
      </a>
    </td>
    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
    <td valign='bottom'>
      <a href='https://demo.rybbon.net/claim?claimcode={}' style='color: #ffffff; background-color: #0084ff; border-radius: 5px;  text-decoration: none;padding: 5px;margin: 0;font-size: 18px;outline: none; min-width:  120px;padding-left: 10px; padding-right: 10px;text-align: center;display: inline-block;'>Get Now</a>
      <br>
      <div style='font-family:Verdana;font-size:12px; color:#666666'>
        <a href='https://demo.rybbon.net/claim?claimcode={}'>Available</a> until August 4, 2021
      </div>
    </td>
  </tr>
</table>
<p>

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.