Talon.One is a powerful, flexible system that can be tailored to your needs. While there are many ways to achieve your overall goal, every integration must notify the Talon.One rule engine of customers and their activities using our Integration API.

You do not need to use the API directly if you are using one of our supported shops. In that situation, you simply install the shop plugin, and the plugin makes the necessary API requests automatically. However, if you operate a custom shop or the official plugin for your shop does not cover your needs, this guide is for you.

Tip: before reading this article you may want to read the article: What Data can I store in Talon.One?

In this article you will learn:

How to input data into Talon.One

By making your first API request to Talon.OneBefore you can start sending customer data to the API, you will need the following information:

  • Your .talon.one subdomain
  • Application ID
  • Application Key

You can find the application ID in the URL by opening your shop in the Campaign Manager and checking the URL in your address bar. It should have the form https://{your_subdomain}.talon.one/shops/{your_shop_id}.

You can find the application key in the Applications tab. Click the Developer section in the bottom left corner of the side bar and click Applications under settings. If this tab is not visible, you will need to ask an account administrator to share the key with you.

Armed with these three pieces of data, we can make our first API request. 

Create a customer profile

A customer profile should correspond to a user that you can reliably identify. This might be logged in users, or it could include logged out users if you have persistent anonymous sessions or some other identification mechanism. The example PHP code below assumes a logged in user with a database ID.

Go ahead and run this script (after updating the variables at the top), and you should see a JSON response describing the new state of this customer:

Congratulations! You've now created a profile that can be used by the Talon.One rules engine. You can view this customer profile in the Customers tab of your shop in the Campaign Manager https://{subdomain}.talon.one/shops/{shop_id}/customers. To add more data or update the profile, simply repeat the request with any fields you want to update.

Note: You can check the API documentation to see what other properties you can include with a customer profile. Fields that are omitted will be ignored.

In the above response, we saw that there is a session object containing a bunch of empty fields. A new ephemeral session is always created for a customer profile update because this activity doesn't logically belong to any particular session. In the next section, we will create a new session and add some events.

Starting first customer session

Normally, you want to group customer activities with some sort of repeated activity within your system. The canonical example is: Making a purchase in an e-commerce shop. You would begin a customer session the first time you see the customer, then close that session whenever they complete a purchase.

Like customer profiles, the ID of customer sessions is controlled by your integration. We recommend using a combination of the user ID and an order counter or some other unique identifier for the current transaction. We use this technique in the next section, which demonstrates starting a session when a user has added an item to their cart:

In the response, we should see the same profile information we added before. As with customer profile updates, you can update a session by repeating the above request with the fields you want to update.  

Effects and coupon codes

You might have noticed the event.effects property in the integration responses. If an update causes a customer session or profile to match any campaign rules, the effects of those rules will be listed here. As an example, we're going to see what happens when a valid coupon code is added to the session.

First, we need to create a new campaign in the campaign manager. Give it any name, and choose to add some unique coupon codes when prompted. Once the campaign has been created, go to the coupons section and copy one of the coupon codes into the following code snippet:

In the response we should now see a value in sessions.discounts:

As well as a setDiscount effect in event.effects:

The effects may contain multiple setDiscount calls with the same discount name ("Coupon Discount" above). The session.discounts object will always reflect the last value for a particular discount. Checking the session.discounts object is important to avoid accidentally applying duplicate discounts as in the following example:

Review 

You should now be familiar with the following steps for integrating Talon.One:

  1. Creating and updating customer profiles
  2. Creating and updating customer sessions
  3. Observing the effects of campaign rules
Or, if you have other questions, don't hesitate to contact us at support@talon.one