Skip to main content

Text Message API > Klaviyo

Updated

SMS API - Klaviyo Integration Guide

 

Overview

This guide describes a step-by-step setup of a Klaviyo Webhook to hit the Wunderkind SMS API.

 

Limitations

  1. Currently, the Klaviyo Webhook is only available within flows.
  2. Currently, the Klaviyo Webhook does not support coupon codes, web feeds, and product feeds
  3. A Klaviyo Flow must be  triggered by a metric (e.g. Placed Order, Started Checkout), which then causes the webhook to fire.
    1. 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
  4. The messages must be created in your ESP in the JSON body of the Webhook
  5. The Wunderkind endpoint cannot be utilized to pull Email and Phone Data, only send information

 

Table of Contents

  1. Enable MFA
  2. Create the Desired Flow
    2.1 Create the Update Profile Property Block (Optional)
    2.2 Create the Messaging Webhook Block
    2.3 Webhook Structure
  3. Checking the Status of your Sends in Klaviyo

Appendix A

 

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 Update Profile Property Block (Optional)

This custom profile property is used to track the sending message in Klaviyo platform. This will be used as a property of the Wunderkind callback metadata and passed to the webhook request payload.

Note: This block may not be needed if some existing properties (e.g. event_id) in some flows can be used for Klaviyo internal tracking.

 

2.2 Create the Messaging Webhook Block

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

 

2.3 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": "Happy Birthday, {{ person.first_name|default:'' }}!",
 "clickUrl": "https://click.example.com",
 "mediaUrl": "https://example.com/image/1.jpg",
 "callbackData": "callbackData": "{\"messageSendTriggeredAt\":\"{{person.message_send_triggered_at}}\",\"profileID\":\"{{ person.KlaviyoID|default:''}}\",\"metricName\":\"Message Status\",\"flow\":\"Purchase Flow\"}"
}

Notes:

  • profileID is a required field
  • metricName is not required, but recommended. The default value: ‘Message Status’. This value is what will show in the users Event Stream on their Profile

messageSendTriggeredAt and flow are custom fields for Klaviyo internal tracking purposes. You can add whatever fields are desired here for tracking (Section 3).

 

3. Checking the Status of your Sends in Klaviyo

Within Klaviyo, go to: Metrics -> ‘Message Status (new metric auto created)’ -> Activity feed. Here you will be able to check the event history of the responses from Wunderkind’s API.

The response shows the event properties including the callback metadata that you passed previously (i.e. MessageSendTriggeredAt) 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 webhook successfully connected to Wunderkind’s message API. 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 will be named whatever was selected as the “Metric Name” field in the JSON body. They are in order:

  1. PENDING_TO_SEND
  2. SENDING
  3. 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

 

Related articles

Powered by Zendesk