Text Message API - Technical Specification

Overview

Wunderkind's Text Message API exposes 5 RESTful endpoints. These allow clients to:

1. Send text messages through the Wunderkind platform
2. Call the status of the sent text message
3. Check the subscription status of a user within the Wunderkind text program
4. Unsubscribe a user (or group of user's) from the Wunderkind text program

Table of Contents

1. Limitations
2. Send A Text Message Using Message API
   2.1 Overview
   2.2 URL
   2.3 Request Headers
   2.4 Body Parameters
   2.5 Responses
   2.6 Examples
3. Send Bulk Text Messages Using Message API
   3.1 Overview
   3.2 URL
   3.3 Request Headers
   3.4 Body Parameters
   3.5 Responses
   3.6 Examples
4. Message Status API
   4.1 Overview
   4.2 URL
   4.3 Request Headers
   4.4 Query Parameters
   4.5 Responses
   4.6 Examples
   4.7 Receive Message Status
5. Subscription Status API
   5.1 Overview
   5.2 URL
   5.3 Request Headers
   5.4 Body Parameters
   5.5 Responses
   5.6 Examples
6. Unsubscribe Users API
   6.1 Overview
   6.2 URL
   6.3 Request Headers
   6.4 Body Parameters
   6.5 Responses
   6.6 Examples

Limitations

• Rate limit: 100 requests/second/website
• Automated callbacks to client owned endpoints do not have retry logic implemented

Send A Text Message Using Message API

Overview

Allows the delivery of text messages from a platform external to the Wunderkind ecosystem (ESP, CDP, etc.).

URL

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

Request Headers

The following are used for authentication/authorization checks.

X-Client-ID: A 32-byte hashed string provided by Wunderkind.
X-Client-Secret: A 64-byte hashed string provided by Wunderkind.

Body Parameters

Model:

{
    "phone": "string",
    "email": "string",
    "text": "string",
    "mediaUrl": "string",
    "clickUrl": "string",
    "callbackData": "string",
    "sendPurpose": "string"
} 

phone - (optional) E. 164 formatted phone number, e.g. +19191234567. This field can be empty if email is specified. Either phone or email must be specified.

email - (optional) the email address will be used to look up the subscribed phone number which
the message will send to. This field can be empty (or will be ignored even if filled) if the phone is specified. Either phone or email must be specified. 

text - (required) the content of the text message

mediaUrl - (optional) the url of the media (e.g. an image)

clickUrl - (optional) the url of the click link. The url will be shortened to a txts.ly tracking link. The click through link can include any custom parameters for tracking

e.g. https://www.clickthru.com/?custom1=example&custom2=example2

callbackData - (required) json formatted string. The json formatted metadata will be appended to the callback request payload for tracking purposes. This can be used to tie the message status to the user profile.

Note: If your system does not require a callback, please utilize a dummy value 

"callbackData": "{}"

sendPurpose - (required) used for passing the purpose/use case of the text API send. This
value is used for Wunderkind internal reporting and can be an internal campaign id, tracking code or a short string. This field supports an alphanumeric string including “-”, ”_” and spaces between words.
e.g. ‘test-send purpose’, ‘code_1’, etc. (Input Length: Maximum 100 characters)

Responses

Success Response - 200

Model:

{
    "messageId": "string"
} 

messageId - the ID to distinguish the specific text message to the end user. This value is automatically generated by Wunderkind system, e.g. b2f25e55-3967-4434-a214-87bb7c8ed013

Error Responses

Model:

{
    "code": 0,
    "message": "string",
    "details": []
} 

code - error code

message - error message

Details - (optional) additional info will be appended here

Error Codes

401 - Unauthorized
403 - Forbidden
429 - Denied (exceed the limits)
4XX(others) - Bad Request
5XX - Internal Server Error

Examples

Request:

curl -X 'POST' \
'https://api.wknd.ai/text/message/send' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Client-ID: ********s19bvx18vly70bk5********' \
-H 'X-Client-Secret: ********c2a4b82f10f8a137b1b056c6f3f3909ddc062a6fb6b4826c********' \
-d '{
"phone": "+19191234567",
"email": "",
"text": "Brand: test message",
"mediaUrl": "https://www.example.com/testimg.png",
"clickUrl": "https://www.example.com/clickme",
"callbackData": "{\"profileID\":\"123456789\",\"Flow\":\"Example Flow\"}"
 }'

Response:

{
    "messageId": "f9eea82a-ce63-4dfa-ae8e-09b891f446cc"
}

Send Bulk Text Messages Using Message API

Overview

Allows the delivery of bulk text messages from a platform external to the Wunderkind ecosystem (ESP, CDP, etc.).
Request Body can have max 50000 messages per request and a minimum of 1.

URL

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

Request Headers

The following are used for authentication/authorization checks.

X-Client-ID: A 32-byte hashed string provided by Wunderkind.
X-Client-Secret: A 64-byte hashed string provided by Wunderkind.

Body Parameters

Model:

{
   "messages": [
      {
         "phone": "string",
         "email": "string",
         "text": "string",
         "mediaUrl": "string",
         "clickUrl": "string",
         "callbackData": "string",
         "sendPurpose": "string"
      }
   ]
}

phone - (optional) E. 164 formatted phone number, e.g. +19191234567. This field can be empty if email is specified. Either phone or email must be specified.

email - (optional) the email address will be used to look up the subscribed phone number which
the message will send to. This field can be empty (or will be ignored even if filled) if the phone is specified. Either phone or email must be specified. 

text - (required) the content of the text message

mediaUrl - (optional) the url of the media (e.g. an image)

clickUrl - (optional) the url of the click link. The url will be shortened to a txts.ly tracking link. The click through link can include any custom parameters for tracking

e.g. https://www.clickthru.com/?custom1=example&custom2=example2

callbackData - (required) json formatted string. The json formatted metadata will be appended to the callback request payload for tracking purposes. This can be used to tie the message status to the user profile.

Note: If your system does not require a callback, please utilize a dummy value 

"callbackData": "{}"

sendPurpose - (required) used for passing the purpose/use case of the text API send. This
value is used for Wunderkind internal reporting and can be an internal campaign id, tracking code or a short string. This field supports an alphanumeric string including “-”, ”_” and spaces between words.
e.g. ‘test-send purpose’, ‘code_1’, etc. (Input Length: Maximum 100 characters)

Responses

Success Response - 200

Model:

{
    "successSent": [
       {
           "status": "string",
           "messageId": "string",
           "phone": "string",
           "email": "string"
       }
    ],
    "failedSent": [
       {
           "errorMessage": "string",
           "phone": "string",
           "email": "string"
      }
   ]
}

messageId - the ID to distinguish the specific text message to the end user. This value is automatically generated by Wunderkind system, e.g. b2f25e55-3967-4434-a214-87bb7c8ed013

Error Responses

Model:

{
    "code": 0,
    "message": "string",
    "details": []
} 

code - error code

message - error message

Details - (optional) additional info will be appended here

Error Codes

401 - Unauthorized
403 - Forbidden
429 - Denied (exceed the limits)
4XX(others) - Bad Request
5XX - Internal Server Error

Examples

Request:

curl --location 'https://api.wknd.ai/text/bulk/message/send' \
--header 'X-Client-ID: ******16s1f59j10fc1z8vx4d8******' \
--header 'X-Client-Secret: ************ejcixob33u5dbr4vix5octiqc0gjrtq3f506fueb************' \
--header 'Content-Type: application/json' \
--data-raw '{
       "messages": [
          {
              "phone": "+12017XXX891",
              "email": "",
              "text": "type your message here.",
              "mediaUrl": "https://www.example.com/testimg.png",
              "clickUrl": "https://www.example.com/clickme",
              "callbackData": "client can put the json formatted metadata here, when our system hit the webhook to update the message status, this '\''callbackData'\'' will be appended in the request payload",
              "sendPurpose": "example_bulk_send"
         },
        {
             "phone": "",
             "email": "",
             "text": "type your message here.",
             "mediaUrl": "https://www.example.com/testimg.png",
             "clickUrl": "https://www.example.com/clickme",
             "callbackData": "client can put the json formatted metadata here, when our system hit the webhook to update the message status, this '\''callbackData'\'' will be appended in the request payload",
             "sendPurpose": "example_bulk_send"
        }
    ]
}'

Response:

{
     "successSent": [
          {
               "status": "Accepted",
               "messageId": "ea5fe19f-31e8-441f-bf7e-8bed1bf8927f",
               "phone": "+12017XXX891",
               "email": ""
          }
  ],
  "failedSent": [
         {
             "errorMessage": "Email, Phone or text is required",
             "phone": "",
             "email": ""
         }
    ]
}

Message Status API

Overview

Returns the send status of the given message ID. The status will be kept for 7 days.

URL

GET https://api.wknd.ai/text/message/status?messageId={messageID}

Request Headers

The following are used for authentication/authorization checks.

X-Client-ID: A 32-byte hashed string provided by Wunderkind.
X-Client-Secret: A 64-byte hashed string provided by Wunderkind.

Query Parameters

messageId - (required) a string. This is the message ID that will be passed to get the status,
e.g. f9eea82a-ce63-4dfa-ae8e-09b891f446cc

Responses

Success Response - 200

Model:

{
    "status": "string"
}

status - the status of given message ID.

Status Codes

• 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

Error Responses

Model:

{
    "code": 0,
    "message": "string",
    "details": []
} 

code - error code

message - error message

Details - (optional) additional info will be appended here

Error Codes

401 - Unauthorized
403 - Forbidden
429 - Denied (exceed the limits)
4XX(others) - Bad Request
5XX - Internal Server Error

Examples

Request:

curl -X 'GET' \
'https://api.wknd.ai/text/message/status?
messageId=f9eea82a-ce63-4dfa-ae8e-09b891f446cc' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Client-ID: ********s19bvx18vly70bk5********' \
-H 'X-Client-Secret: ********c2a4b82f10f8a137b1b056c6f3f3909ddc062a6fb6b4826c********'

Response:

{
    "status": "DELIVERED"
} 

Receive Message Status

Wunderkind's system can automatically callback an existing API endpoint with the message status. To do so, the following information needs to be collected for Wunderkind system settings before performing the callback.

Note: Wunderkind cannot support token authentication, only POST or PUT requests.

Required Information

• Callback URL: the url for making the callback
• Header: Request headers (e.g. key, secret, etc.)

Examples

POST https://example.endpoint.com/user

Headers:

"X-Client-ID": "miu39r98mjrys73upzi9l4kqfbxxxxxx",
"X-Client-Secret": "oj07v6m137t1uhuf4w2c4dglvi093xahdb2unrrydlrxkxxxxxxxxxxx"

Payload:

{
    "messageID": "540e8400-e29b-41d4-a716-446655440000",
    "status": "DELIVERED",
    "phone": "++11234567890",
    "email": "test@example.com",
    "callbackData": "{\"key1\":\"value1\",\"key2\":\"value2\"}"
}

Subscription Status API

{
    "phone_numbers": {
        "phone_numbers": [
            "+11234567890",
            ]

        },
        "csv_file": "cGhvbmVfbnVtYmVycworMTEyMzQ1Njc4OTAKKzE5ODc2NTQzMjEw"
}

phone_numbers
+11234567890
+19876543210

{
    "phoneNumberStatuses": [
        {
            "phoneNumber": "+11234567890",
            "subscriptionStatus": false
        },
        {
            "phoneNumber": "+19876543210",
            "subscriptionStatus": false
        }
    ],
    "invalidPhoneNumbers": [ ]
}

{
    "code": 0,
    "message": "string",
    "details": []
}

curl -X 'POST' \
'https://api.wknd.ai/text/subscription/status' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Client-ID: ********s19bvx18vly70bk5********' \
-H 'X-Client-Secret: ********c2a4b82f10f8a137b1b056c6f3f3909ddc062a6fb6b4826c********' \
-d '{
    "phone_numbers": ["+11234567890", "+19876543210"]
}'

{
    "phoneNumberStatuses": [
        {
            "phoneNumber": "+11234567890",
            "subscriptionStatus": false
        },
        {
            "phoneNumber": "+19876543210",
            "subscriptionStatus": false
        }
    ],
    "invalidPhoneNumbers": []
}

curl -X 'POST' \
'https://api.wknd.ai/text/subscription/status' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Client-ID: ********s19bvx18vly70bk5********' \
-H 'X-Client-Secret: ********c2a4b82f10f8a137b1b056c6f3f3909ddc062a6fb6b4826c********' \
-d '{
    "csv_file": "cGhvbmVfbnVtYmVycworMTEyMzQ1Njc4OTAKKzE5ODc2NTQzMjEw"
}'

{
    "phoneNumberStatuses": [
        {
            "phoneNumber": "+11234567890",
            "subscriptionStatus": false
        },
        {
            "phoneNumber": "+19876543210",
            "subscriptionStatus": false
        }
    ],
    "invalidPhoneNumbers": []
}

{
"phone_numbers": {
"phone_numbers": [
"+11234567890",
]

},
"csv_file": "cGhvbmVfbnVtYmVycworMTEyMzQ1Njc4OTAKKzE5ODc2NTQzMjEw"
}

phone_numbers
+11234567890
+19876543210

{
    "message": "We have received and are processing your request",
    "invalidPhoneNumbers": ["string"]
}

{
    "code": 0,
    "message": "string",
    "details": []
}

curl -X 'POST' \
'https://api.wknd.ai/text/unsubscribe' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Client-ID: ********s19bvx18vly70bk5********' \
-H 'X-Client-Secret: ********c2a4b82f10f8a137b1b056c6f3f3909ddc062a6fb6b4826c********' \
-d '{
    "phone_numbers": ["+11234567890", "+19876543210"]
}'

{
    "message": "We have received and are processing your request",
    "invalidPhoneNumbers": []
}

curl -X 'POST' \
'https://api.wknd.ai/text/unsubscribe' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Client-ID: ********s19bvx18vly70bk5********' \
-H 'X-Client-Secret: ********c2a4b82f10f8a137b1b056c6f3f3909ddc062a6fb6b4826c********' \
-d '{
    "csv_file": "cGhvbmVfbnVtYmVycworMTEyMzQ1Njc4OTAKKzE5ODc2NTQzMjEw"
}'

{
    "message": "We have received and are processing your request",
    "invalidPhoneNumbers": []
}