1. 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

2. 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

2.1 Create the webhook block

The webhook shown here will be responsible for triggering the message.

2.2 Webhook Structure

This webhook will use the following structure:

URL: https://api.wknd.ai/text/message/send

Headers:

X-Client-Key: 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

2.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

3. 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":

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

Step-1: Navigate to Analytics>Dashboards and select "Create Dashboard" in the top right corner
Step-2: After naming your dashboard, select "Add Data View" and "Create from scratch"

Step-3: Here you can select the type of graph you would like to utilize to view the data, the following example shows a line graph
Step-4: 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"

Step-6: 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-