Overview
This guide describes a step-by-step setup of a Klaviyo Webhook to hit the Wunderkind SMS API.
Table of Contents
- Limitations
- Enable MFA
-
Create the Desired Flow
3.1 Create the webhook block
3.2 Webhook structure
3.3 Performance and click tracking - Testing a Newly Created Webhook
-
Checking the Status of your Sends in Klaviyo
5.1 General overview of the webhook performance
5.2 Detailed view of the callback status
Appendix A - Example Birthday Flow
Appendix B - Message Status Listing
1. Limitations
- Currently, the Klaviyo Webhook is only available within flows.
- Currently, the Klaviyo Webhook does not support coupon codes, web feeds, and product feeds
-
A Klaviyo Flow must be triggered by a metric (e.g. Placed Order, Started Checkout), which then causes the webhook to fire.
- Currently, the Klaviyo Flows do not support pulling in the Klaviyo ID as a dynamic field for date-triggered flows. We are in conversation with Klaviyo to get this updated
- The messages must be created in your ESP in the JSON body of the Webhook
- The Wunderkind endpoint cannot be utilized to pull Email and Phone Data, only send information
- The Wunderkind endpoint has a rate limit of 100 messages per second
-
As a safety feature, the API will only allow 1 message with the same body to be sent to the same user within a 24hr period
- Changing the "sendPurpose" or "text" values will allow multiple messages to be sent for proofing
2. Enable MFA
Multifactor Authentication is needed when using Klaviyo’s webhooks. You will need to download the Google Authenticator Application. https://help.klaviyo.com/hc/en-us/articles/360026617692
3. Create the Desired Flow
The Wunderkind messages API allows you to send texts based on user actions already existing in your ESP. In Appendix A, there is an example of a date triggered flow to send a text message of birthday wishes to a user if they have not opened their birthday email in the previous 2 hours.
3.1 Create the webhook block
The webhook shown here will be responsible for triggering the message.
3.2 Webhook Structure
This webhook will use the following structure:
URL: https://api.wknd.ai/text/message/send
Headers:
X-Client-ID: provided by Wunderkind
X-Client-Secret: provided by Wunderkind
Json body:
{
"phone": "{{ person.phone_number|default:'' }}",
"email": "{{ person.email }}",
"text": "BrandName: Happy Birthday, {{ person.first_name|default:'' }}!",
"clickUrl": "https://click.example.com",
"mediaUrl": "https://example.com/image/1.jpg",
"callbackData":"{\"profileID\":\"{{ person.KlaviyoID|default:''}}\",\"metricName\":\"Flow Name\",\"flow\":\"Flow Name\"}" ,
"sendPurpose": "Flow Name"
}
Notes:
-
profileID is a required field
- This allows the status callback to be tied to the correct user record
-
sendpurpose is a required field
- This allows the messages to be tracked separately on the Wunderkind side
- clickUrl is not a required field but if a URL is added, it must be a working URL
- mediaUrl is not a required field but if a URL is added, it must be a working image URL
-
metricName is not required, but recommended to allow for dashboard creation.
- The best practice is to utilize the same Webhook Name as the metricName, sendPurpose, and flow
- These values should be the same for each webhook block but unique across all sends to allow for better tracking in Klaviyo/Wunderkind
- Additional fields can be added to the callbackData for enhanced tracking
3.3 Performance and Click Tracking
The Messages API sends have auto-applied UTMs from the Wunderkind backend. To accurately track these sends in your analytics platform you can add additional UTMs/URL parameters to the link in Klaviyo.
URL: https://click.example.com
Parameter: utm_api=birthday
Json body:
{
...
"clickUrl": "https://click.example.com?utm_api=birthday",
...
}
Notes:
- Multiple parameters can be added, e.g.
- https://click.example.com?utm_api=birthday&utm_tracking=newclicks
4. Testing a Newly Created Webhook
Once the Webhook block is created, you can insert a subscribed phone number into the JSON to test the SMS content. Replace the phone line with your own phone number or a colleagues that is subscribed to the SMS marketing program:
{
"phone": "+15163334444",
"email": "{{ person.email }}",
"text": "BrandName: Happy Birthday, {{ person.first_name|default:'' }}!",
"clickUrl": "https://click.example.com",
"mediaUrl": "https://example.com/image/1.jpg",
"callbackData":"{\"profileID\":\"{{ person.KlaviyoID|default:''}}\",\"metricName\":\"Flow Name\",\"flow\":\"Flow Name\"}" ,
"sendPurpose": "Flow Name"
}
You can then click into "Preview" and "Send Test Request":
5. Checking the Status of your Sends in Klaviyo
The statuses of all message API sends are automatically sent back to your Klaviyo instance. Within the platform, the performance of the campaigns can be viewed through the Dashboards UI. This section will walk through the creation of a simple dashboard and finding a more detailed view of the callbacks for troubleshooting purposes.
5.1 General overview of the webhook performance
- Navigate to Analytics>Dashboards and select "Create Dashboard" in the top right corner
- After naming your dashboard, select "Add Data View" and "Create from scratch"
- Here you can select the type of graph you would like to utilize to view the data, the following example shows a line graph
-
Each webhook created will require a separate dashboard, the metric chosen will be the Flow Name selected in step 2, as sends are delivered Klaviyo will automatically create the metric name so the dashboard can only be created AFTER the flow has been set live.
- In the example screenshot below, the metricName is "Message Status"
- Once the metric is selected, you can filter by Status. The most common/important statuses will be "Delivered", "NOT FOUND", "NOT SUBSCRIBED", "FAILED TO MATCH" and "FAILED TO DELIVERY"
- The dashboard will populate with live send data
5.2 Detailed view of the callback status
Typically this detailed view of the send will not be required except in certain troubleshooting scenarios. Within Klaviyo, go to: Metrics -> ‘Flow Name’ -> Activity feed. You will need to replace "Flow Name" with the value chosen in the webhook. Here you will be able to check a detailed event history of the responses from Wunderkind’s API.
The response shows the event properties including the callback metadata that you passed previously and the properties that wunderkind API sent back (i.e. MessageID, Status).
MessageID and $event_id are utilized by Wunderkind for troubleshooting. You can see in the attached image that the Status was “Delivered” meaning that the sms was successfully delivered to the end user. A complete listing of the possible message status values can be found in Appendix B.
Within the user profile, each successful send will generate 4 actions. The first will be “Webhook Send Successful” denoting that the call to the Wunderkind API endpoint has been made and a 200 status code was received.
The following 3 events are generated by the Wunderkind platform and the value will be whichever one replaced "Flow Name" in the JSON body of the webhook. They are in order:
- PENDING_TO_SEND
- SENDING
- DELIVERED
A complete list of message statuses are listed in Appendix B.
Appendix A - Example Birthday Flow
Appendix B - Message Status Listing
Within the user profile, each successful send will generate 4 actions. The first will be “Webhook Send Successful” denoting that the call to the Wunderkind API endpoint has been made and a 200 status code was received.
-
NOT_FOUND
- This response will be sent if no subscription with this phone number is found.
-
NOT_SUBSCRIBED
- This response will be sent if the phone number found is not subscribed
-
FAILED_TO_MATCH
- This response indicates that the email sent has not sms matches or too many device IDs tied to it. Too many device IDs tied to the user is indicative of super users (typically internal to the company)
-
PENDING_TO_SEND
- This response indicates that the message has been received and is preparing to be delivered
-
SENDING
- This response indicates that the message has been sent to our text aggregator for delivery to the end user
-
FAILED_TO_SEND
- This indicates that an unexpected error has occurred before the message was sent to our text aggregator for delivery
-
DELIVERED
- This response serves as confirmation from our text aggregator and the service provider (Verizon, AT&T, T-Mobile, etc.) that the message has been delivered successfully
-
FAILED_TO_DELIVERY
- This indicates that a downstream error has occurred with either our text aggregator or the service provider
Comments
0 comments
Article is closed for comments.