Skip to main content

Text Message API

Updated

Message API Implementation Guide

 

Message API Specification v1.1

Message API Endpoints

  • Send Message
    • URL
    • Headers
    • Body Parameters
    • Responses
    • Examples
      • Klaviyo
      • Salesforce
  • Get Status
    • URL
    • Headers
    • Query Parameters
    • Responses
    • Examples

Information Collection for Callback

  • Klaviyo
  • Salesforce
  • Other Callback APIs

 

Message API Endpoints

Message API exposes 2 RESTful endpoints.

Rate limit: 100 requests/second/website (identified by the request header ‘X-Client-ID’)

 

Send Message

Sends an external message, then returns the message ID.

 

URL

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

 

Headers

X-Client-ID: the client ID. It’s a 32-byte hashed string which is provided by Wunderkind.

X-Client-Secret: the client secret. It’s a 64-byte hashed string which is provided by Wunderkind.

These 2 request headers are used for authentication/authorization checks.

 

Body Parameters

Model:

Unset
{
"phone": "string",
"email": "string",
"text": "string",
"mediaUrl": "string",
"clickUrl": "string",
"callbackData": "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

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.

 

Responses

200 - OK

Model:

Unset
{
"messageId": "string"
}

messageId - (required) the ID to distinguish the text messages. This is automatically generated
by Wunderkind system, e.g. b2f25e55-3967-4434-a214-87bb7c8ed013

Error responses:

Model:

Unset

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

code - (required) error code

message - (required) error message

Details - (optional) additional info will be appended here

 

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

 

Examples: 

Klaviyo

Request:

Unset
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": "test message",
"mediaUrl": "https://www.example.com/testimg.jsp",
"clickUrl": "https://www.example.com/clickme",
"callbackData": "{\"profileID\":\"****3QW1DV42YDCQND5YJ2****\",\"metricName\":\"Message
Status Test\",\"flow\":\"Test Flow\"}"
}'

Response: 

Unset

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

 

Salesforce

Request: 

Unset
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": "",
"email": "test@example.com",
"text": "test message",
"mediaUrl": "https://www.example.com/testimg.jsp",
"clickUrl": "https://www.example.com/clickme",
"callbackData":
"{\"customObject\":\"WkndTextExternalSend__c\",\"customObjectID\":\"a5jRK0000000A0zYAE\",\"b
ackfilledFieldNameForEmail\":\"Email__c\",\"backfilledFieldNameForPhone\":\"Phone__c\",\"bac
kfilledFieldNameForMessageID\":\"Message_ID__c\",\"backfilledFieldNameForSendStatus\":\"Send
_Status__c\"}"
}'

Response: 

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

 

Get Status

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}

 

Headers

X-Client-ID: the client ID. It’s a 32-byte hashed string which is provided by Wunderkind.
X-Client-Secret: the client secret. It’s a 64-byte hashed string which is provided by Wunderkind.
These 2 request headers are used for authentication/authorization checks.

 

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

200 - OK

Model:

Unset

{
"status": "string"
}

status - (required) the status of given message ID. Possible values of the status:

  • ACCEPTED: indicates the message has been accepted by Wunderkind system
  • NOT_FOUND: indicates the given phone number or the phone number found by the given email address is not found in Wunderkind system
  • NOT_SUBSCRIBED: indicates the phone number is not text subscribed in Wunderkind system
  • SENDING: indicates the message is being sent
  • FAILED_TO_SEND: indicates it failed to send the message. The failure came from Wunderkind system
  • DELIVERED: indicates the message was delivered to the phone number
  • FAILED_TO_DELIVERY: indicates it failed to deliver the message.

Error responses:

Model:

Unset

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

code - (required) error code
message - (required) error message
details - (optional) additional info will be appended here.

 

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

Examples

Request: 

Unset

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: 

Unset

{
"status": "DELIVERED"
}

 

Information Collection for Callback

Message API can automatically call the Klaviyo and Salesforce APs to update the send status in the ESP system. To do so, the following information needs to be collected for Wunderkind system settings before performing the callback.

Klaviyo

  • Callback URL - the url for making the callback. Default value: https://a.klaviyo.com/api
  • API Key - the API Key for callback authentication e.g. pk_ef3734a5ec4e6e9f42d654cd8ce825****

Salesforce

  • Callback URL: the url for making the callback
  • Auth URL: the url for retrieving the access token
  • Token: the refresh token for retrieving the access token
  • Username: the username for retrieving the access token
  • Password: the password for retrieving the access token
  • API Key: the client ID for retrieving the access token
  • API Secret: the client secret for retrieving the access token

Other Callback APIs

  • Callback URL: the url for making the callback
  • Header: Request header

Examples

Header for API Key:

Unset

"headers": {
"Authorization: "API-Key pk_68bfd****"
}

Header for bearer token: 

Unset

"headers": {
"Authorization: "Bearer
eyJhbGciOiJSUzI1NiIsImtpZCI6ImJlNzgyM2VmMDFiZDRkMmI5NjI3NDE2NThkMjA4MDdlZmVlNmRlNWMiLCJ0eXAi
OiJKV1QifQ.eyJpc3MiOiJodHRwczovL3NlY3VyZXRva2VuLmdvb2dsZS5jb20vYngtc3RhZ2luZy1jb3JlYXBpIiwiY
XVkIjoiYngtc3RhZ2luZy1jb3JlYXBpIiwiYXV0aF90aW1lIjoxNzAyNTY0NjMxLCJ1c2VyX2lkIjoicGxBbzJ5eXY2N
U5UY1U0TW9CakZTOWZNQTJFMyIsInN...."
}
  • Method: “POST” or “PUT”

 

Related articles

Powered by Zendesk