Text Message API - Ometria Integration Guide

Overview

This guide describes a step-by-step setup of an Ometria Webhook to hit the Wunderkind Text Message API.

Table of Contents

1. Limitations
2. Create Wunderkind Connections
   2.1 Connection Fields
   2.2 Template Guide
   2.3 Activating the Connection
   2.4 General Notes
3. Create the Desired Automated Campaign
   3.1 Define the entry condition
   3.2 Create Webhook Block
4. Testing a Newly Created Webhook
   4.1 Create a Test Segment
   4.2 Create a Test File
   4.3 Duplicate the Desired Automated Campaign
   4.4 Upload the Test File
5. Checking the Status of your Sends

1. Limitations

1. The only tracking available is within the GA4/Adobe platforms via UTMs
2. The Wunderkind endpoint has a rate limit of 250 messages per second which allows batch messaging to be delivered via Webhook
3. 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. Create Wunderkind Connections

The connection can be created by going to Settings>Connections>Add new connection>Webhook:

2.1 Connection Fields

Webhook endpoint URL:

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

HTTP Headers:

{"X-Client-ID" : "provided by Wunderkind", "X-Client-Secret" : "provided by Wunderkind"}

Template:

{
"phone": "{{ profile.phone_number_country }}{{ profile.phone_number }}", 
"email":"{{ profile.email }}", 
"text": "Brand Name: Your message Content", 
"mediaUrl": "The URL of any images you would like displayed",
"clickUrl": "The URL that will be included in the message, including UTMs", 
"callbackData": "{}", 
"sendPurpose": "A send-specific parameter for internal Wunderkind tracking"
}

2.2 Template Guide

• phone and email are semi-optional fields
  • Either phone number OR email address must be included
• text is a required field. This is where the message content is specified
  • Please note that the brand name should be included at the beginning or as part of the message body:
    • Brand Name: Happy birthday, take this free shipping on us!
    • Wishing you a happy birthday from Brand Name!
• 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
  • This parameter should be used to include URL tracking information e.g. utm_campaign=example_1
  • The entire click URL will be shortened as it flows through the Wunderkind backend, including the applied URL parameters
• mediaUrl is not a required field but if a URL is added, it must be a working image URL
  • This will turn the message into an MMS
• callbackData is a required field that has no use in the Ometria integration

Template Example

{
"phone": "{{ profile.phone_number_country }}{{ profile.phone_number }}", 
"email":"{{ profile.email }}", 
"text": "Brand Name: Happy birthday, enjoy free shipping on us!", 
"mediaUrl": "https://wkd.wpengine.com/wp-content/uploads/2023/04/wk-char-RGB-chinobg-Academic-2x-1-1.svg", 
"clickUrl": "https://www.wunderkind.co/?utm_campaign=birthday_sms_1", 
"callbackData": "{}", 
"sendPurpose": "Birthday SMS"
}

2.3 Activating the Connection

To successfully test the webhook and transition it from pending->active, you will need to replace the dynamic phone value with a static value e.g. "+123".

Template Testing Example

{
"phone": "+123", 
"email":"{{ profile.email }}", 
"text": "Brand Name: Happy birthday, enjoy free shipping on us!", 
"mediaUrl": "https://wkd.wpengine.com/wp-content/uploads/2023/04/wk-char-RGB-chinobg-Academic-2x-1-1.svg", 
"clickUrl": "https://www.wunderkind.co/?utm_campaign=birthday_sms_1", 
"callbackData": "{}", 
"sendPurpose": "Birthday SMS"
}

Once you see the "Connection test successful" you can change it back and click update to save the Connection and allow it to be used in your campaigns.

2.4 General Notes

• A new connection should be made for each message
  • An existing one can be updated as long as it is no longer in use
• Merge Tags can be added in jinja to the text field to add user fields

  {{ profile.firstname }}

• Fallback conditions can be applied in case the properties don't exist for all users

  {% if profile.firstname %}
      {{ profile.firstname }}
  {% else %}
      'default_value'
  {%endif %}

3. Create the Desired Automated Campaign

Please review the Ometria documentation for an overview on using webhooks in automation campaigns. The Webhook to send a text message from the Wunderkind platform can be added to an existing flow or a net new flow. In the example below we will be creating a net new flow that will send a text message on the user's birthday. Navigate to Campaigns>Automation Campaigns and select "Create new campaign".

3.1 Define the entry condition

The flow needs an entry condition to be defined, here we will be setting this to send on the contact's birthday with re-entry allowed every 51 weeks.

3.2 Create Webhook Block

The webhook block is what will trigger the send from the Wunderkind backend. You will need to select the Connection created in Step 2. 

4. Testing a Newly Created Webhook

4.1 Create a Test Segment

Navigate to Customer>Saved Segments and select Create a new static segment. The naming here does not matter but you can see the title Wunderkind SMS Test below:

4.2 Create a Test File

Testing the newly created webhook will require a test segment. It is recommended to create and save a CSV file of email addresses and phone numbers you will consistently be using for testing with the format below:

* Please note that the phone numbers must be uploaded with the country code in E164 format (e.g. +123456789). Ometria Documentation This file can easily be created using Google Sheets or Excel and saved in .csv format. An Example csv file is attached titled "ometria test file".

*Please note that the phone numbers must be subscribed to the text program

4.3 Duplicate the Desired Automated Campaign

You'll need to navigate to the Automation you created in Step 4 and duplicate the automated campaign:

Once you have created the duplicate automated campaign, you must change the entry condition, allowing it to be triggered by users entering your test segment:

*The duplicated campaign must be set live for the SMS to be sent!

4.4 Upload the Test File

Once the entry condition has been changed, you can navigate to Contact Upload to upload the Test Segment File created in Step 4.2:

Please see the screenshot below for the settings required. Click "Upload" when you are done.

*Please note that this can take a few minutes, you will see the completed status after refreshing your screen. Once this has been completely uploaded, the Test Segment users should receive the SMS/MMS for review.

5. Checking the Status of your Sends

The performance of each SMS campaign can be viewed within GA4/Adobe via the custom utm_campaign values appended when the campaign was created.