Attentive

Attentive is a text-message marketing tool. Once connected, every Toki event reaches the customer's Attentive subscriber record as a custom event, together with their up-to-date loyalty attributes, so you can start Attentive journeys from loyalty moments and segment or personalize your texts with loyalty data. The same connection subscribes customers in Attentive when they complete your Newsletter sign up reward.

The connection is one-way: Toki writes to Attentive. Everything you build on that data, such as journeys and segments, you build in Attentive.

What you need from Attentive

Toki asks for one thing: an API Key. In Attentive, API keys belong to a custom app, so you create one small app for Toki and copy its key.

Create the custom app and copy the key

In Attentive, open the App Marketplace page (Attentive's integrations setup page).
Click + Create App in the top-right corner.
In App name, enter a unique name, for example "Toki".
In Contact email, enter your email address. Attentive uses it to reach you if there is a problem with the app.
Set the permissions listed below. Attentive starts every API at No Access.
Click Create. The Copy API key window appears.
Click Copy. This is the only time Attentive shows the key, so paste it somewhere safe, such as a password manager, before you close the window with X.

The app now appears on the Built by you tab of the App Marketplace page. Treat the key like a password: anyone who has it can send messages to your customers on your behalf.

Permissions the key needs

Attentive API	Permission	Toki uses it to
Custom Events	Write	Send Toki events to the customer's subscriber record.
Custom Attributes	Write	Keep the customer's `toki_` attributes current.
Subscribers	Write	Subscribe customers who complete the Newsletter sign up reward.

Leave eCommerce, Privacy Request, and Product Catalog at No Access. Toki never uses them.

Connect Attentive

In the Toki app, open Integrations.
On the Attentive row, click Install.
On the Install Attentive page, paste the key into API Key.
Click Save in the bar at the top of the page.

You return to the Integrations list and the Attentive row shows Installed. There is nothing else to switch on: from now on, every Toki event and every profile property goes to Attentive.

Toki stores the key as you enter it and uses it from the next event on. Attentive is the one that checks it, each time Toki sends something, so paste it exactly as Attentive showed it. A wrong key shows up later as events that never reach Attentive; see "Troubleshooting" below.

Attentive lists a Toki event once a customer has triggered it. If you want an event to exist in Attentive before launch, trigger it yourself with a test member; see "Troubleshooting" below.

The install, manage, and uninstall flow is the same for every integration; see Integrations and your API key.

Change or disconnect

To replace the key, click Manage on the Attentive row. The Manage Attentive page shows the key you saved; paste the new one into API Key and click Save.

If you regenerate the key in Attentive (on the Built by you tab, open the app, click Regenerate in the API key section, then Yes, regenerate), the old key stops working, so paste the new key into Toki right away. Regenerating keeps the app and its journeys; deleting the app is a separate action that disconnects every journey the app's events started, for good.

To disconnect, click Uninstall on the row and confirm. Toki deletes the key it stored and stops sending events. Nothing changes in your Attentive account: the events and attributes already sent stay there.

What Toki sends to Attentive

Each time something happens to a customer in Toki, such as earning points, reaching a tier, or redeeming a reward, Toki sends it to Attentive as a custom event named after the Toki event, for example Toki Points Earned, with the details of that moment as event properties.

Right after each event, Toki also sends the customer's current loyalty data as custom attributes that all start with toki_, such as toki_point_balance, toki_tier_name, and toki_referral_link. Toki sends them with every event, not just the ones that changed.

The complete list of events, their properties, and the profile properties is in Email and SMS events. To see exactly what Toki holds for one member, open their profile and choose User properties from the More actions menu; the same article explains it.

Toki identifies the customer in Attentive by the email address on their Toki member profile. Phone numbers are not part of what Toki sends. Toki sends events for customers who have an email address in Toki and are members of the store. Suspended members get no events while the suspension lasts.

Attentive accepts the events and attributes even for people who are not subscribed to your Attentive messages yet. For the data to reach a text subscriber, their Attentive record needs the same email address as their Toki profile.

Event names in Attentive

Every event keeps its Toki name, with the "Toki" prefix: Points Earned in a Toki campaign or workflow is the custom event Toki Points Earned in Attentive. That includes the four events that Klaviyo and Postscript show under other names. In Attentive they are Toki Membership Unlocked, Toki Membership Lost, Toki Referred a Friend, and Toki Voting Activity Completed, exactly as in Toki.

How attributes look in Attentive

Attributes arrive under the same names as in the reference, for example toki_point_balance, toki_tier_name, toki_nt_name, and toki_loyalty_nt_points. You don't need to create them in Attentive first: Attentive adds each attribute the first time Toki sends it, under exactly that name.

Attentive has no limit on the number of custom attributes, and it accepts attribute names of up to 200 characters. Toki's own names are far shorter. Survey, quiz, and poll answers are named after the activity's Alias and each question's Alias, so keep those short.

Rewards and features that use Attentive

Newsletter sign up reward

The Newsletter sign up reward (under Other in the catalog) has its own form in the wallet and on your storefront. With Subscription source set to Toki form and Attentive connected, Toki passes each sign-up on to Attentive:

A customer completes the reward: in the wallet they click Complete, or on your storefront they enter their email address in the Newsletter Sign Up Embed. Toki creates a member for the email address if there is none yet.
Toki subscribes that email address to marketing in Attentive. Attentive's own sign-up rules then apply to the new subscriber.
Toki completes the reward. That also fires the Toki Newsletter Sign Up event, so you can welcome the subscriber from an Attentive journey.

To set the reward up:

Open Loyalty. In Ways to Earn, click Add new activity.
Under Other, pick Newsletter sign up.
In the Rules card, set Subscription source to Toki form.
Set up the reward, set Status to Active, and click Save.

With Subscription source set to Shopify email subscription, the sign-up happens in Shopify and this reward sends nothing to Attentive. The Phone step of the Toki form works through Klaviyo; see Klaviyo. For the rest of the reward's settings, see Creating rewards.

Toki signs the customer up for your Attentive marketing messages by email, with the locale English (United States). Attentive accepts the sign-up only when your account has exactly one API sign-up unit for marketing in that locale, and it uses that unit to opt the customer in, so what the customer receives next follows that unit's settings. If sign-ups don't show up in Attentive, ask Attentive to check your API sign-up units.

Other places you will see Attentive

Gift card delivery set to External sends the gift card events to Attentive; see Gift card delivery.
Approving or rejecting a review sends Toki Review Approved or Toki Review Rejected to Attentive; see Review moderation.
The Send Custom External Event workflow action can send an event you name to Attentive; see Workflow actions.
Survey, quiz, and poll answers reach Attentive as attributes named after the activity's Alias; see Creating rewards.
Customers' wallet pass download links reach Attentive as toki_apple_download_link and toki_google_download_link; see Wallet passes.

Attentive adds no reward of its own to the catalog, and no segment or tier condition reads from Attentive.

Typical setups built on Toki events

You build the journeys and segments in Attentive; Toki supplies the custom events and attributes. These are the combinations merchants use most:

You want to…	Start from this Attentive custom event	Useful properties
Welcome new members	Toki Account Created	Attributes `toki_referral_link` and `toki_point_balance`
Congratulate a customer on a new tier	Toki Membership Unlocked	Event property `toki_tier_name`; attribute `toki_tier_rewards`
Win back a customer who dropped out of a tier	Toki Membership Lost	Event property `toki_tier_name`
Confirm points as they come in	Toki Points Earned	Event properties `amount` (points just earned), `toki_point_balance`, and `toki_points_earned` (lifetime total)
Text a discount code a customer earned	Toki Reward Created	Event properties `toki_code`, `toki_type`, and `toki_value`
Thank a customer whose friend placed an order	Toki Referred a Friend	Event properties `toki_referee_email` and `toki_order_amount`
Welcome a newsletter subscriber	Toki Newsletter Sign Up	Event property `toki_discount_code`, when the reward issues one
Remind customers about wishlisted products	Toki Wishlist Item Added	Event properties `toki_product_id`, `toki_variant_id`, and `toki_label`
Follow up on survey or quiz answers	Toki Voting Activity Completed	Attributes `toki_<activity alias>_<field alias>`, one per answer
Tell customers how close they are to the next tier	Any	Attributes `toki_loyalty_nt_points` and `toki_nt_name`; `toki_nt_spend_left` for tiers that unlock by spend
Add wallet pass links to any text	Any	Attributes `toki_apple_download_link` and `toki_google_download_link`

Use Toki Account Created for welcome journeys: it fires when the customer's loyalty account is created, so the journey runs for new members only.

Start a journey from a Toki event

Every Toki event Attentive has received is available as a trigger for both email and text message journeys.

In Attentive, open the Journeys tab and click + Create journey.
Click Start from scratch. The list of triggers includes Toki's custom events, such as Toki Points Earned.
Pick the event and set up the journey. In its messages, Insert Variable offers the event's properties.

To use Toki's attributes:

In a message, click Variable in the message composer and find the toki_ attribute in the Subscriber category, under CUSTOM.
In a segment, open Segments, click Create segment, then Create next to Dynamic segment. For Choose condition, select A subscriber's characteristics, pick the toki_ attribute in the Custom Attributes section, and choose the values to include.

Troubleshooting

"API Key is required" when you save. The API Key field is empty. Paste the key from Attentive's Copy API key window. If you closed that window without copying, regenerate the key in Attentive (see "Change or disconnect" above) and paste the new one.

Events or toki_ attributes are not showing up in Attentive. Open Integrations and check that the Attentive row shows Installed; Toki only sends events to connected tools. Then check the key: Attentive checks it with every event, so a mistyped key, or one you have since regenerated in Attentive, means events stop arriving. Paste the current key on the Manage Attentive page. In Attentive, check that the custom app has Write for Custom Events and Custom Attributes. The customer needs an email address in Toki and must not be suspended. Attributes travel with events, so a customer who has not triggered any event since you connected has no toki_ attributes yet.

A Toki event is not in Attentive's list yet. Attentive lists a Toki event after the first time a customer triggers it. To make an event exist before launch, trigger it with a test member. For example, credit a few points to a member from their profile to send Toki Points Earned; see Adjust a member's balance.

Newsletter sign-ups are not reaching Attentive. Open the reward and check that Subscription source is Toki form. In Attentive, check that the custom app has Write for Subscribers. Attentive's own sign-up rules decide when the new subscriber counts as subscribed.

You deleted the custom app in Attentive. Create a new custom app, paste its key on the Manage Attentive page, and rebuild the journeys that started from Toki events: Attentive disconnects a deleted app's journeys for good, even if you create a new app later.