NAV
http

Introduction

Using the MessageWhiz API, you can create message campaigns, send individual SMS messages or entire message broadcasts, manage recipients, senders, unsubscribers lists, and create and manage templates, tokens and links.

This document will guide you through the core endpoints and functionality of the Message Whiz API, so you can quickly and efficiently start your messaging.

Getting started

In this section, we describe all the necessary steps to send your first broadcast via the MW API.

To start, MessageWhiz uses API keys to allow access to the API. You can find your API key in your personal MW account page.

To properly access the MessageWhiz platform, the API key needs to be included in the header for all API requests to the server.

Sending First Broadcast

In order to send the basic message broadcast, you need to perform the following steps:

Generic replaceable

The following variables should be replaced with your actual information in requests:

Key Description
<apikey> Personal API key
<url> URL from which API is accessed - https://sms.messagewhiz.com/

Campaigns

A Campaign unifies a set of SMS messages grouped under one campaign name. The campaign exists in a specified time period, thus start and end dates should be indicated during campaign creation.

Create a Campaign

Example Request

POST /api/3/campaign HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "name":"CampaignName",
    "start_date":"2020-07-22T21:00:00.000Z",
    "end_date":"2020-09-25T21:00:00.000Z"
}

Example Response (200 OK)

{
   "errorCode": 0,
   "errorMessage": "",
   "errorType": "",
   "executionTime": 0.044941952,
   "result": {
       "id": 46279,
       "is_default": 0,
       "name": "CampaignName",
       "start_date": "2020-07-22T21:00:00.000Z",
       "end_date": "2020-09-25T21:00:00.000Z",
       "enabled": true
   }
}

Create a Campaign from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/campaign

Request Body

In the request body specify details for the Campaign that will be created.

Required parameters:

Optional parameters:

Date and time are expressed according to ISO 8601.

Get Campaigns

Request Example

GET /api/3/campaign?start=0 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

Response Example (200 OK)

{
   "errorCode": 0,
   "errorMessage": "",
   "errorType": "",
   "executionTime": 0.012664016,
   "result": [
       {
           "enabled": true,
           "id": 46279,
           "is_default": 0,
           "name": "CampaignName",
           "start_date": "2020-07-22T21:00:00.000Z",
           "end_date": "2020-09-25T21:00:00.000Z",
           "userList": [
               {
                   "campaign_id": 46279,
                   "user_id": 3191,
                   "company_id": 3182
               }
           ]
       },
       {
           "enabled": true,
           "id": 34641,
           "is_default": 1,
           "name": "Default campaign",
           "start_date": null,
           "end_date": null,
           "userList": [
               {
                   "campaign_id": 34641,
                   "user_id": 3191,
                   "company_id": null
               }
           ]
       }
   ]
}

Get Campaigns from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/campaign

Query Parameters

You can include several parameters in your GET query in order to receive only the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active campaigns
filter disabled filtering by the specific campaign name
start 0 the number of items to skip

As an example, to get first two inactive campaigns, the query URL will be the following:

GET https://sms.messagewhiz.com/api/3/campaign?limit=2&enabled=false

To get the Campaign by the name:

GET https://sms.messagewhiz.com/api/3/campaign?filter=name=CampaignName

Modify a Campaign

PUT Request Example

PUT /api/3/campaign/46279 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "end_date":"2021-03-25T21:00:00.000Z"
}

Response Example (200 OK)

{
   "errorCode": 0,
   "errorMessage": "",
   "errorType": "",
   "executionTime": 0.026245764,
   "result": {
       "id": 46279,
       "is_default": 0,
       "name": "CampaignName",
       "start_date": "2020-07-22T21:00:00.000Z",
       "end_date": "2021-03-25T21:00:00.000Z",
       "enabled": true
   }
}

PATCH Request Example

PATCH /api/3/campaign/46279 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "enabled": "1"
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.013305616,
    "result": {
        "id": 46279,
        "enabled": 1
    }
}

To modify a specific Campaign from your MessageWhiz account, include its ID in the query:

PUT https://sms.messagewhiz.com/api/3/campaign/{id}

For instance, PUT https://sms.messagewhiz.com/api/3/campaign/46279, where 46279 is the ID of the Campaign that will be replaced using the data presented in the request body.

If you want to partially update the resource, you can use:

PATCH https://sms.messagewhiz.com/api/3/campaign/{id}

Request Body

In the request body specify the value you want to modify, for instance:

{ "end_date":"2021-03-25T21:00:00.000Z" }

Disable a Campaign

Request Example

DELETE /api/3/campaign/46317 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
   "errorCode": 0,
   "errorMessage": "",
   "errorType": "",
   "executionTime": 0.034133648,
   "result": true
}

To remove a specific Campaign from your MessageWhiz account, add its ID as parameter to the query:

DELETE https://sms.messagewhiz.com/api/3/campaign/{id}

Recipients

Here you can manage your recipients - basically phone numbers grouped into lists of recipients to whom the messages will be sent. Some additional metadata related to each recipient might be included in the recipient lists and used in the broadcasts.

You have two options for the recipient list creation:

Please make sure to enter the number in the international format, including the country code. For example, enter 18756785619 if you are sending an SMS to a recipient from the USA or Canada, where 1 is the country code.

Create a Recipient List (import a file)

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/RecipientList?truncate=true' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}' \
--form 'name=FirstRecipientList'

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.032846168,
    "result": {
        "inserted": 4,
        "total": 4,
        "wrong": 0,
        "duplicate": 0,
        "recipient_list_id": 267628
    }
}

Create a Recipient List by importing file of contacts:

POST https://sms.messagewhiz.com/api/3/RecipientList?truncate=true

Request Body

In the request body, specify the Recipient List details:

(e.g {"0":"phone_number", "1":"first_name"}).

The mapping structure should correspond to the structure presented in the uploaded file.

The metadata stored in these marked columns might be used as tokens to send personalized messages.

(e.g /Users/userName/dir/recipients.csv).

Query Parameters

Parameter Default Description
truncate false automatically truncates fields in the list if they are longer than allowed.

first_name, last_name - max length is 50 symbols, email, url - 255, other - 5000.

if truncate===false and there are fields in the list that exceed the limits, an error while loading occurs.

To check if your file fits, you can preview it.

Create a Recipient List (manually)

Request Example

POST /api/3/recipientList/numbers HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "name": "ManuallyAddedList",
    "numbers": ["380503327227", "380848122639"]
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.018502512,
    "result": {
        "inserted": 2,
        "wrong": 0,
        "duplicate": 0,
        "total": 2,
        "recipient_list_id": 267888,
        "count": 2
    }
}

Create a Recipient List by adding the phone numbers manually:

POST https://sms.messagewhiz.com/api/3/recipientList/numbers

Request Body

In the request body, specify the Recipient List details:

Preview a Recipient List

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/recipientList/1/preview' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' 

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.00777864,
    "result": {
        "data": [
            [
                "phone_number",
                "first_name"
            ],
            [
                "6593333311",
                "Anthony"
            ],
            [
                "6593333322",
                "Bob"
            ],
            [
                "6593333333",
                "Jonathan"
            ],
            [
                "6593333344",
                "Alex"
            ]
        ],
        "isAllNum": [
            true,
            false
        ],
        "isExceedLength50": [
            false,
            false
        ],
        "isExceedLength255": [
            false,
            false
        ],
        "isExceedLength5000": [
            false,
            false
        ]
    }
}

MessageWhiz API provides you with the possibility to preview your file of contacts before importing it and creating the Recipient List:

POST https://sms.messagewhiz.com/api/3/recipientList/6/preview

Request Body

In the request body, you should specify:

Get Recipient Lists

Request Example

GET /api/3/RecipientList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.012814664,
    "result": [
        {
            "id": 267891,
            "name": "SecondRecipientList",
            "enabled": 1,
            "count": 4
        },
        {
            "id": 267888,
            "name": "ManuallyAddedList",
            "enabled": 1,
            "count": 2
        },
        {
            "id": 267628,
            "name": "FirstRecipientList",
            "enabled": 1,
            "count": 4
        },
        {
            "id": 222345,
            "name": "ev",
            "enabled": 1,
            "count": 1
        }
    ]
}

Get Recipient Lists from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/RecipientList

Query Parameters

You can include several parameters in your GET query in order to receive the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active lists
filter disabled filtering by the specific list name
start 0 the number of items to skip

For example, to get only the Recipient List with specific name(e.g SecondRecipientList), use the following query:

https://sms.messagewhiz.com/api/3/RecipientList?filter=name=SecondRecipientList

Get Recipients from Recipient List

Request Example

GET /api/3/recipientList/267628/recipients HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.008162772,
    "result": [
        {
            "phone_number": 6593333311,
            "first_name": "Anthony"
        },
        {
            "phone_number": 6593333322,
            "first_name": "Bob"
        },
        {
            "phone_number": 6593333333,
            "first_name": "Jonathan"
        },
        {
            "phone_number": 6593333344,
            "first_name": "Alex"
        }
    ]
}

Get recipients from the specific Recipient List using its ID:

GET https://sms.messagewhiz.com/api/3/recipientList/{id}/recipients

The response contains an object for each recipient in the list, including their metadata (first_name, last_name,email, url, custom).

Get Numbers from Recipient List

Request Example

GET /api/3/recipientList/267628/listNumbers HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.008841536,
    "result": [
        "6593333311",
        "6593333322",
        "6593333333",
        "6593333344"
    ]
}

Get an array of phone numbers from the specific Recipient List using its ID:

GET https://sms.messagewhiz.com/api/3/recipientList/{id}/listNumbers

Download a Recipient List

Request Example

GET /api/3/recipientList/267628/download HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

"phone_number";"first_name"
"6593333311";"Anthony"
"6593333322";"Bob"
"6593333333";"Jonathan"
"6593333344";"Alex"

Download specific Recipient List using its ID and save the response:

GET https://sms.messagewhiz.com/api/3/recipientList/267628/download

Modify a Recipient List (manually)

PUT Request Example

PUT /api/3/recipientList/267891/numbers HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "name": "Mw-manual",
    "numbers": ["380503322227"]
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.019542036,
    "result": {
        "inserted": 1,
        "wrong": 0,
        "duplicate": 0,
        "total": 1,
        "recipient_list_id": 267891,
        "count": 5
    }
}

PATCH Request Example

PATCH /api/3/RecipientList/267891 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "name": "EditingList",
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.031447856,
    "result": {
        "name": "EditingList",
        "enabled": true,
        "count": 5
    }
}

To modify a specific Recipient List by adding new numbers manually or changing the list name, add its ID to the query:

PUT https://sms.messagewhiz.com/api/3/recipientList/{id}/numbers

In the request body specify the new values for this list:

If you want to just partially update the resource(by changing the list name), you can use:

PATCH https://sms.messagewhiz.com/api/3/RecipientList/{id}

Modify a Recipient List (import a file)

PUT Request Example

curl --location --request PUT 'https://sms.messagewhiz.com/api/3/recipientList/267891' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/RecipientList.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name", "2":"last_name"}' \
--form 'name=NewList'

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.027778432,
    "result": {
        "inserted": 4,
        "total": 4,
        "wrong": 0,
        "duplicate": 0,
        "recipient_list_id": 267891
    }
}

Replace the entire existing Recipient List with the new imported one:

PUT https://sms.messagewhiz.com/api/3/recipientList/{id}

Request Body

In the request body specify the new values for this list:

(e.g {"0":"phone_number", "1":"first_name", "2":"last_name"}).

The mapping structure should correspond to the structure presented in the new uploaded file.

Disable a Recipient List

Request Example

DELETE /api/3/RecipientList/267891 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.011510284,
    "result": true
}

To remove a specific Recipient List from your MessageWhiz account, you should include its ID the query:

DELETE https://sms.messagewhiz.com/api/3/RecipientList/{id}

Senders

Sender is generally a number, name, or ID that recipients see on their devices when they receive a message from you. Here's how to manage a single sender entity.

Create a Sender

Example Request

POST /api/3/sender HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "name": "FirstSender"
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.044570548,
    "result": {
        "id": 28938892,
        "name": "FirstSender",
        "enabled": true
    }
}

Create a Sender from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/sender

Request Body

In the request body only specify a name of the Sender that will be created,

e.g. "name": "FirstSender"

Get Senders

Request Example

GET /api/3/sender? HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.013848856,
    "result": [
        {
            "enabled": true,
            "id": 28938892,
            "name": "FirstSender"
        },
        {
            "enabled": true,
            "id": 28905672,
            "name": "test"
        }
    ]
}

Get Senders from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/sender

Query Parameters

You can include several parameters in your GET query in order to receive only the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active senders
filter disabled filter by the specific sender name
start 0 the number of items to skip

Modify a Sender

PUT Request Example

PUT /api/3/sender/28905672 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
   "name": "TestSender"
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.021960496,
    "result": {
        "id": 28905672,
        "name": "TestSender",
        "enabled": true
    }
}

To modify a specific Sender from your MessageWhiz account, include its ID in the query:

PUT https://sms.messagewhiz.com/api/3/sender/{id}

Request Body

In the request body specify the new sender name and status for the selected Sender entity, for instance:

{ "name": "TestSender", "enabled": 0 }

If you want to partially update the resource, you can use:

PATCH https://sms.messagewhiz.com/api/3/sender/{id}

Request Body

In the request body specify the new Sender status, for instance:

{ "enabled": 0 }

Disable a Sender

Request Example

DELETE /api/3/sender/28938891 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.012125844,
    "result": true
}

To remove a specific Sender from your MessageWhiz account, you should include its ID to the query:

DELETE https://sms.messagewhiz.com/api/3/sender/{id}

Sender Lists

MessageWhiz provides you with the possibility to group multiple Senders into one Sender List,
from which a Sender will be randomly select for each broadcast message.

Create a Sender List

Example Request

POST /api/3/senderList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "name":"FirstSenderList",
    "senderIds": [28938892, 28905674]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.046940544,
    "result": {
        "id": 5456,
        "name": "FirstSenderList",
        "enabled": true,
        "count": 2
    }
}

Create a Sender List from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/senderList

Request Body

In the request body specify the following:

In case of all invalid senderIds, Senders will not be added to the list, and the list will be created empty.

Add Senders to a Sender List

Example Request

POST  /api/3/senderList/5456/senders HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "ids": [28899614, 28899615]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.032248508,
    "result": [
        28899614, 28899615
    ]
}

To add Senders to a Sender List from your MessageWhiz account, specify Sender List ID:

POST https://sms.messagewhiz.com/api/3/senderList/{listId}/senders

Request Body

In the request body specify an array of Sender Ids "ids": [,] that will be added to the list.

Get Sender Lists

Request Example

GET /api/3/senderList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.00982226,
    "result": [
        {
            "enabled": true,
            "id": 5456,
            "name": "FirstSenderList",
            "count": 2
        },
        {
            "enabled": true,
            "id": 5455,
            "name": "SenderList",
            "count": 1
        }
    ]
}

Get Sender Lists from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/senderList

Query Parameters

You can include several parameters in your GET query in order to receive only the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active sender lists
filter disabled filter by the specific sender list name
start 0 the number of items to skip

Get Senders from the List

Request Example

GET /api/3/senderList/5456/senders HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.008722612,
    "result": {
        "id": 5456,
        "senders": [
            {
                "senderId": 28905674,
                "name": "test2"
            },
            {
                "senderId": 28938892,
                "name": "FirstSender"
            }
        ]
    }
}

Get an array of Sender objects from a specific Sender List:

GET https://sms.messagewhiz.com/api/3/senderList/{id}/senders

Modify a Sender List

PUT Request Example

GET /api/3/senderList/5456 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
{
    "name": "New",
    "senderIds": [28938892, 28905674]
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.040806108,
    "result": {
        "id": 5456,
        "name": "New",
        "enabled": true,
        "count": 2
    }
}

PATCH Request Example

PATCH /api/3/senderList/5456 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "enabled": true,
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.009910892,
    "result": {
        "id": 5456,
        "enabled": 1
    }
}

To modify a specific Sender List by adding new Senders and changing the list name, add its ID to the query:

PUT https://sms.messagewhiz.com/api/3/sendertList/{id}

In the request body specify the new values for this list:

If you want to just partially update the resource(by enabling or disabling it), you can use:

PATCH https://sms.messagewhiz.com/api/3/RecipientList/{id}

Disable a Sender List

Request Example

DELETE /api/3/senderList/5457 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.017833028,
    "result": true
}

To remove a specific Sender List from your MessageWhiz account, you should include its ID in the query:

DELETE https://sms.messagewhiz.com/api/3/senderList/{id}

Disable a Sender in the Sender List

Request Example

DELETE /api/3/senderList/5456/senders?id=28905674 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.013993384,
    "result": true
}

To remove a Sender from the Sender List, you should include Sender List ID in the query and specify Sender ID as required parameter:

DELETE https://sms.messagewhiz.com/api/3/senderList/{listID}/senders?id={senderID}

Send a Broadcast

Estimate Broadcast

Example Request

POST /api/3/Broadcast/estimate HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "broadcast_type": 11,
    "recipient_list_ids": "288696",
    "unsubscriber_list_ids": "",
    "message_body": "sample"
}

Example Response

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 5.076538867,
    "result": {
        "messages": 1,
        "sum": 3.36,
        "parts": 1,
        "recipient_id_map": [],
        "replacements": {},
        "firstSegmentCount": 1,
        "recipient_meta_data_map": [
            [
                3852004823,
                {
                    "phone_number": 3852004823,
                    "email": "email@gmail.com",
                    "custom": "Custom",
                    "url": "https://google.com",
                    "first_name": "John",
                    "last_name": "Doe"
                }
            ]
        ],
        "recipients": {
            "3852004823": {
                "rate": 3.36,
                "mccMnc": 111222
            }
        },
        "messageExpanded": {
            "actions": {
                "callback": {
                    "replacement": "",
                    "uuid": "",
                    "count": 0
                },
                "first_name": {
                    "replacement": "",
                    "count": 0
                },
                "last_name": {
                    "replacement": "",
                    "count": 0
                },
                "url": {
                    "replacement": "",
                    "count": 0
                },
                "random_symbol": {
                    "replacement": "h",
                    "count": 0
                },
                "verification_code": {
                    "replacement": "",
                    "count": 0
                },
                "custom": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "custom1": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "custom2": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "custom3": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "custom4": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "gender": {
                    "replacement": "",
                    "count": 0
                },
                "word_spinner": {
                    "replacement": "",
                    "count": 0,
                    "parameters": [],
                    "isApproximate": true
                },
                "link": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "link_list": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "unsubscription_link": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "shorten_url": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                },
                "callback_link": {
                    "replacement": "",
                    "count": 0,
                    "parameters": []
                }
            },
            "text": "sample"
        },
        "links": {},
        "warnings": [],
        "estimateHash": "8572aeb3624293a238cd2d7cd901fb61743e3a435e50e00d631a410cb0044d39dd4a53be35e040974f88c7e3799ab1f8d1629455c260a87b0fa48da547c7ffcb",
        "batchEstimation": {
            "messages": 1,
            "sum": 3.36,
            "parts": 1
        }
    }
}

To Estimate a broadcast via API:

POST sms.messagewhiz.com/api/3/Broadcast/estimate

Request Parameters

Required:

Optional:

Fast Single

Example Request

POST /sms HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json

{
    "api_key": <apikey>,
    "to": "2605876689",
    "from": "sender",
    "text": "sample message"
}

Example Response

{
  "message_id": "rbzAV2NXxJ_u5bDL35Hop"
}

Example DLR Callback

{
  "message_id": "rbzAV2NXxJ_u5bDL35Hop",
  "sender": "sender",
  "recipient": "5417543010",
  "content": "Message Text",
  "state": 2,
  "status": "DELIVRD",
  "client_ref": "Custom param",
  "timestamp": "2023-03-28T15:52:31.279Z",
  "parts_count": 1,
  "price": 2,
  "parts": [
    {
      "pdu_id": "SVV7oRyvMLX1OIzLwta2p",
      "encoding": 0,
      "content": "Message Text",
      "status": "DELIVRD"
    }
  ]
}

Example link click Callback

{
  "message_id": "4iE_yS65Vn8iXCqaW5L2N",
  "link_id": "hkzt.me/ZPFuT5",
  "time": "2023-05-01T13:46:37.921Z",
  "unique_click": true
}

Error codes/Validation errors:

without mandatory field "text":

{
  "statusCode": 400,
  "message": [
    "text must be shorter than or equal to 100000 characters",
    "text must be longer than or equal to 1 characters",
    "text should not be empty"
  ],
  "error": "Bad Request"
}

without mandatory field "to":

{
  "statusCode": 400,
  "message": [
    "The recipient number entered is invalid. Please ensure that the number is between 10 and 15 digits in length."
  ],
  "error": "Bad Request"
}

without mandatory field "from":


{
  "statusCode": 400,
  "message": [
    "Sender must not exceed 11 letters (latin alphabet or special symbols “'._-+&{space}” are allowed) or 20 numbers."
  ],
  "error": "Bad Request"
}

without mandatory field "api_key":


{
  "statusCode": 401,
  "message": "Unauthorized"
}

To send a single message from your MessageWhiz account:

POST https://sms.messagewhiz.com/sms

Request Body

Required parameters:

Optional parameters:

Initial HTTP Response

Response on DLR callback

When a single message was sent, we got a response with information about the sent message and DLR status.

Parameters:

After the user’s click on the link, an additional response with the click info appears.

Parameters:

Send a Tiny single (OLD)

Example Request

POST /api/3/Broadcast/tiny/ HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "recipient": "2605876689",
    "sender": "sender",
    "message_body": "sample message"
}

Example Response (200)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.049512918,
    "result": {
        "broadcastId": 1174181,
        "segmentId": 523940
    }
}

To send a tiny single message from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/Broadcast/tiny/

Request Body

In the request body, the following single message components can be used.

Required parameters:

Send a Single message (OLD)

Example Request

POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
 "name":"Single SMS to 380681337228",
 "campaign_id":1,
 "broadcast_type":10,
 "unsubscriber_list_ids":"",
 "sender_id":"23",
 "recipient":"380681337228",
 "message_body":"message body",
 "custom_parameter":"1234abcd5678efgh"
}

Example Response (200 OK)

{
  "errorCode":0,
  "errorMessage":"",
  "errorType":"",
  "executionTime":0.160202353,
  "result": {
    "broadcastID":331,
    "segmentID":493,
    "custom_parameter":"1234abcd5678efgh"
  }
}

To send a single message from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/Broadcast

Request Body

In the request body, the following single message components can be used.

Required parameters:

Optional parameters:

Send a Base Broadcast

Example Request

POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
 "name":"broadcast",
 "campaign_id":1,
 "broadcast_type":11,
 "unsubscriber_list_ids":"",
 "sender_ids":"23",
 "recipient_list_ids":"12",
 "message_body":"broadcast message",
}

Example Response (200 OK)

{
  "errorCode":0,
  "errorMessage":"",
  "errorType":"",
  "executionTime":0.446636071,
  "result": {
    "broadcastID":333,
    "segmentID":494
  }
}

To send a Basic Broadcast from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/Broadcast

Request Body

In the request body, the following broadcast components can be used.

Required parameters:

Optional parameters:

Send a Smart Broadcast

Example Request

POST /api/3/Broadcast HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
 "name":"manual",
 "campaign_id":1,
  "broadcast_type":12,
 "unsubscriber_list_ids":"",
 "sender_ids":"23",
 "recipient_list_ids":"12",
 "message_body":"man message",
 "send_date":"2021-03-01T12:41:38.837Z",
 "utc_offset":120,
 "eb_type":"manual",
 "first_segment_size":"3",
}

Example Response (200 OK)

{
  "errorCode":0,
  "errorMessage":"",
  "errorType":"",
  "executionTime":0.446636071,
  "result": {
    "broadcastID":333,
    "segmentID":495
  }
}

To send a Smart Broadcast from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/Broadcast

In the request body, the following broadcast components can be used.

Required parameters:

To send the Manual Smart Broadcast add the following parameters.

Required parameters:

Optional parameters:

To send the CTR Threshold Smart Broadcast add the following parameters.

Required parameters:

Optional parameters:

Continue smart broadcast

Example Request

POST /api/3/Segments HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "broadcast_id": 111
    "message_body": "sample"
    "segment_size": 1
    "send_now": true
    "sender_ids": "1"
    "utc_offset": 180
}

Example Response

{
  "errorCode":0,
  "errorMessage":"",
  "errorType":"",
  "executionTime":2.202010018,
  "result":{
        "real_price":0,
        "id":1,
        "broadcast_id":111,
        "utc_offset":180,
        "message_body":"sample",
        "template_id":null,
        "batch_index":null,
        "state":0,
        "recipient_count":1,
        "estimated_price":3.36,
        "send_conditions_id":1,
        "enabled":true,
        "created_at":"2021-06-25 14:02:50",
        "send_time":"2021-06-25 14:02:50",
        "estimated_count":1
  }
}

To continue a smart broadcast:

POST sms.messagewhiz.com/api/3/Segments

Request Parameters

Required:

Optional:

Send One time password (OTP)

Example Request

POST /api/broadcasts/single?otp=true HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
 "campaign_id": 1,
 "sender_id": "23",
 "message_body": "verification code: {{verification_code}}",
 "send_date": "2021-03-01T12:41:38.837Z",
 "utc_offset": 120,
 "recipient": "2605876689",
 "verification": true
}

Example Response (200 OK)

{
    "id": 123
}

To send a single sms with an OTP from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/broadcasts/single?otp=true

Request Body

You can pass such parameters in the request body

Required parameters:

Optional parameters:

Verify OTP

Example Request

POST /api/recipients/{phone_number}/verification HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "verification_code": 2253
}

Example Response (200 OK)

{
    "valid": true
}

To verify an OTP which was sent earlier:

POST https://sms.messagewhiz.com/api/recipients/{phone_number}/verification

Where {phone_number} should be substituted with the phone number of the recipient to whom the OTP has been sent.

Request Body

Only one parameter should be passed in the request body:

Get Broadcasts List

Example Request

GET /api/3/Broadcast/List HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json 

Example Response

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.351626371,
    "result": [
        {
            "id": 200,
            "user_id": 123,
            "name": "sample broadcast",
            "type": 1,
            "message_body": "sample message",
            "enabled": 1,
            "trigger_id": null,
            "send_date": "2041-03-07T11:41:55.000Z",
            "state": 2,
            "parent_id": null,
            "real_price": 0,
            "estimated_price": 10.50,
            "create_date": "2019-08-05T13:20:04.000Z",
            "estimated_count": 8,
            "utc_offset": 0,
            "next_segment_size": null,
            "eb_type": null,
            "company_name": "sample company",
            "timezone": "GMT +0",
            "send_now": false,
            "broadcastConversion": {
                "uniqueClicks": 0,
                "totalClicks": 0,
                "recipientCount": 8,
                "conversion": "0.00",
                "broadcastId": 200
            }
        }
    ]
}

Get Broadcasts from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/Broadcast/List

Query Parameters

You can include several parameters to your GET query in order to receive only the data you need.

Parameter Default Description
limit 10 the number of items to fetch
start 0 the number of items to skip
filter disabled filtering by the specific broadcast field
orderby create_date DESC criteria and order by which the broadcasts will be sorted

Parameters possible values

Available parameters are:

For example filter with such format:
?filter=name=sample,type=2,type=12,filterBy=create_date,start_date=06/01/2021 12:00 AM
Will find all the smart broadcasts (both approaches) that was created later than 06/01/2021 12:00 AM which name contains sample substring

Single request broadcasts

Example Request

POST /api/3/Broadcast/combinedsubmit HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "message_body": "hello {{first_name}} {{last_name}} here is {{custom2}} click on link {{shorten_url}}!!",
    "sender": "My sender",
    "recipients": [
        {
            "phone_number": 380100001010,
            “first_name": "John",
            "last_name": "Doe",
            "custom2": "MyCustomToken",
            "url": "https://mylink1.com"
        },
        {
            "phone_number": 380100001011,
            "first_name": "Bob",
            "url": "https://mylink2.com"
        }
    ]
}

Example Response


{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.351626371,
    "result": [
        {
            "broadcastID":333,
            "segmentID":495
        }
    ]
}

An endpoint on Segment Based architecture which enables creating a Base Broadcast and sending it to a new Recipient list withone request.

Request parameters

Required

Optional

Unsubscribe Lists

Unsubscribe lists - lists of numbers that will be excluded from recipient lists and will not receive messages from you. An unsubscribe list consists of the numbers that opted out of your broadcasts as well as numbers you added to the list yourself.

Create a Unsubscribe List (import a file)

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/UnsubscribeList?truncate=true' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' \
--form 'mapping={"0":"phone_number", "1":"first_name"}' \
--form 'name=FirstRecipientList'

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.032846168,
    "result": {
        "enabled": true,
        "id": 123,
        "name": "FirstRecipientList",
        "company_id": 1,
        "unsubscribers_amount": 10,
        "user_id": 1
    }
}

Create an Unsubscribe List by importing file of contacts:

POST https://sms.messagewhiz.com/api/3/UnsubscribeList?truncate=true

Request Body

In the request body, specify the Unsubscribe List details:

(e.g {"0":"phone_number", "1":"first_name"}).

The mapping structure should correspond to the structure presented in the uploaded file.

The metadata stored in these marked columns might be used as tokens to send personalized messages.

(e.g /Users/userName/dir/unsubscribers.csv).

Query Parameters

Parameter Default Description
truncate false automatically truncates fields in the list if they are longer than allowed.

first_name, last_name - max length is 50 symbols, email, url - 255, other - 5000.

if truncate===false and there are fields in the list that exceed the limits, an error while loading occurs.

To check if your file fits, you can preview it.

Create an Unsubscribe List (manually)

Example Request

POST /api/3/unsubscribeList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "name":"FirstUnsubscribeList",
    "numbers": [380502222233]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.025868544,
    "result": {
        "enabled": true,
        "id": 21534,
        "name": "FirstUnsubscribeList",
        "company_id": 3182,
        "unsubscribers_amount": 1,
        "user_id": 3191
    }
}

Create an Unsubscribe List from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/unsubscribeList

Request Body

In the request body specify the following:

Preview an Unsubscribe List

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/unsubscribeList/preview/4' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/ numbers_9.csv' 

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.008022008,
    "result": {
        "data": [
            [
                "phone_number"
            ],
            [
                "6593333311"
            ],
            [
                "6593333322"
            ],
            [
                "6593333333"
            ],
            [
                "6593333344"
            ]
        ],
        "isAllNum": [
            true,
            true,
            true,
            true
        ],
        "isExceedLength50": [
            false,
            false,
            false,
            false
        ],
        "isExceedLength255": [
            false,
            false,
            false,
            false
        ],
        "isExceedLength5000": [
            false,
            false,
            false,
            false
        ]
    }
}

MessageWhiz API provides you with the possibility to preview your file of contacts before actually importing it and to create the Unsubscribe List:

POST https://sms.messagewhiz.com/api/3/unsubscribeList/preview

Request Body

In the request body, you should specify:

Add Numbers to Unsubscribe List

Example Request

POST /api/3/UnsubscribeList/21534/members HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "numbers":["380502222233", "380643333322"]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.031270908,
    "result": {
        "inserted": 2,
        "alreadyExists": 0,
        "notValid": 0
    }
}

Add phone numbers to the existing Unsubscribe List (include its ID in the query):

POST https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/members

Request Body

In the request body specify:

Get Unsubscribe Lists

Request Example

GET /api/3/unsubscribeList? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.028108664,
    "result": [
        {
            "id": 21534,
            "name": "FirstUnsubscribeList",
            "enabled": 1,
            "unsubscribers_amount": 3
        }
    ]
}

Get Unsubscribe Lists from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/unsubscribeList

Query Parameters

You can include several parameters to your GET query in order to receive the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active lists
filter disabled filtering by the specific list name
start 0 the number of items to skip

For example, to get only an Unsubscribe List with a specific name(e.g FirstUnsubscribeList), use the following query:

https://sms.messagewhiz.com/api/3/RecipientList?filter=name=FirstUnsubscribeList

Get Numbers from Unsubscribe List

Request Example

GET /api/3/unsubscribeList/21534/members  HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.018904092,
    "result": [
        {
            "phone_number": "380643333322"
        },
        {
            "phone_number": "380502327265"
        },
        {
            "phone_number": "380502222233"
        }
    ]
}

Get phone numbers from the specific Unsubscribe List using its ID:

GET https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/members

Download an Unsubscribe List

Request Example

GET /api/3/unsubscribeList/21534/download HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

"phone_number"
"380502327265"
"380502222233"
"380643333322"

Download a specific Unsubscribe List using its ID and then save the response:

GET https://sms.messagewhiz.com/api/3/unsubscribeList/{id}/download

Modify an Unsubscribe List (import a file)

PUT Request Example

curl --location --request PUT 'https://sms.messagewhiz.com/api/3/UnsubscribeList/21534' \
--header 'apikey: <apikey>' \
--form 'mapping={"0":"phone_number"}' \
--form 'doc=@/home/user/Downloads/UnsubscribeList.csv' 

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.040112328,
    "result": {
        "enabled": true,
        "id": 21534,
        "name": "FirstUnsubscribeList",
        "company_id": 3182,
        "unsubscribers_amount": 4,
        "user_id": 3191
    }
}

PATCH Request Example

PATCH /api/3/UnsubscribeList/21534 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "enabled": false
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.022112432,
    "result": {
        "id": 21534,
        "enabled": false
    }
}

Replace the entire existing Unsubscribe List with the new imported one:

PUT https://sms.messagewhiz.com/api/3/UnsubscribeList/{id}

Request Body

In the request body specify the new values for this list:

(e.g {"0":"phone_number"}).

The mapping structure should correspond to the structure presented in the new uploaded file.

If you want to partially update the resource, you can use:

PATCH https://sms.messagewhiz.com/api/3/UnsubscribeList/{id}

You can disable an unsubscribe list by entering "enabled": false in the request body.

Disable an Unsubscribe List

Request Example

DELETE /api/3/UnsubscribeList/21567 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.01279094,
    "result": true
}

To remove a specific Unsubscribe List from your MessageWhiz account, you should include its ID in the query:

DELETE https://sms.messagewhiz.com/api/3/unsubscribeList/{id}

Links

MessageWhiz provides you with the possibility to include Links in your message broadcasts.
You are able to create and manage Links beforehand, and then just insert them in a message as a Link token({{link:linkId}}).

Example Request

POST /api/3/link HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
  "name":"Link1",
  "url": "https://foot1.com"
  "platform_based_links": {
      "bot_redirect":"https://foot32.com/desktop"
      "preview_url":"https://foot12.com"
  }
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.01954006,
    "result": {
        "id": 165655,
        "name": "Link1",
        "url": "https://foot1.com",
        "enabled": true,
        "type":0,
        "platform_based_links": {
          "bot_redirect":"https://foot32.com/desktop",
          "preview_url":"https://foot12.com"
        }
    }
}

Create a Link from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/link

Request Body

In the request body specify details for the Link that will be created.

Required parameters:

Optional parameters:

Request Example

GET /api/3/link? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.006230324,
    "result": [
        {
            "enabled": true,
            "id": 165655,
            "name": "Link1",
            "url": "https://foot1.com"
        },
        {
            "enabled": true,
            "id": 146746,
            "name": "test",
            "url": "https://sms.messagewhiz.com/app/workspace/links"
        }
    ]
}

Get Links from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/link

Query Parameters

You can include several parameters to your GET query in order to receive only the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active links
filter disabled filtering by the specific link name/url
start 0 the number of items to skip

For example, to get only a Link with specific URL (e.g https://foot1.com), use the following query:

https://sms.messagewhiz.com/api/3/link?filter=url=https://foot1.com,

or to get a Link by name:

https://sms.messagewhiz.com/api/3/link?filter=name=Link1

PUT Request Example

PUT /api/3/link/165655 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
  "name": "FirstLink",
  "url": "https://foot1.com",
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.011805652,
    "result": {
        "id": 165655,
        "name": "FirstLink",
        "url": "https://foot1.com",
        "enabled": true
    }
}

To modify a specific Link, you should specify its ID in the query:

PUT https://sms.messagewhiz.com/api/3/link/{id}

Request Body

In the request body specify the key and value you want to modify, for example:

{ "name": "FirstLink" }

The same parameters as for the link creation can be used.

Request Example

DELETE /api/3/link/165655 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.016383932,
    "result": true
}

To remove a specific Link, you should include its ID in the query:

DELETE https://sms.messagewhiz.com/api/3/link/{id}

Example Request

POST /api/3/details/linkConversion HTTP/1.1
Host: sms.messagewhiz.com
apiley: <apikey>
Content-Type: application/json

{
    "url":"mmdsmart.com"
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.12326038,
    "result": {
        "conversion": 100,
        "totalRecipients": 1,
        "clicks": 1
    }
}

To receive conversion data from a certain link:

POST https://sms.messagewhiz.com/api/3/details/linkConversion

Request Body

Only one parameter should be included within the request body:

Response Explanation

In the response you can receive 3 main parameters:

Link Lists

MessageWhiz provides you with the possibility to group multiple links into one list. With the help of the Link List token, links from the list will be evenly distributed between recipients of the broadcast. Just insert Link List in a message as a token({{link_list:linkListId}}).

Example Request

POST /api/3/LinkList HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "name":"FirstLinkList", 
    "linkIds":["311"]}  

}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.017949384,
    "result": {
        "id": 6940,
        "name": "FirstLinkList",
        "enabled": true,
        "linkListLength": 1,
        "warning":""
    }
}

Create an empty Link List from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/LinkList

Request Body

In the request body specify the name(string) of the Link List that will be created. Either linkIds - an array of IDs of the previously created Links that the list will contain, or links - an array of objects with url and name properties

Example Request

POST /api/3/LinkList/6940/links HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{
    "ids":["146746", "13298"]
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.04211898,
    "result": [
        146746
    ]
}

To add existing Links to the Link List, include Link List ID in the query:

POST https://sms.messagewhiz.com/api/3/LinkList/{id}/links

Request Body

In the request body specify the "ids(array)" an array of IDs of the previously created Links that the list will contain. Or specify one link "id(int)"".

Request Example

curl --location --request POST 'https://sms.messagewhiz.com/api/3/LinkList' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/linkList.csv' \
--form 'mapping={"0":"name", "1":"url"}' \
--form 'name=FirstLinkList'

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.105039176,
    "result": {
        "id": 7077,
        "name": "FirstLinkList",
        "enabled": true
    }
}

Create a Link List by importing the file:

POST https://sms.messagewhiz.com/api/3/LinkList

Request Body

In the request body, specify the Link List details:

The mapping structure should correspond to the structure presented in the uploaded file.

(e.g /Users/userName/dir/linkList.csv).

Example Request

POST /api/3/LinkList/6940/links/bulk HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

{"links":

    [{"name": "some3 name", "url": "https://43.url.com"}, {"name": "some3 name 2", "url": "https://24422.url.com"}]

}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.064860264,
    "result": {
        "enabled": true,
        "id": 6940,
        "name": "FirstLinkList",
        "user_id": 3191,
        "company_id": 3182
    }
}

To add multiple new Links to the Link List, you should include Link List ID in the query:

POST https://sms.messagewhiz.com/api/3/LinkList/{id}/links/bulk

Request Body

In the request body specify:

Request Example

GET /api/3/LinkList? HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.056359856,
    "result": [
        {
            "id": 6943,
            "name": "LinksList",
            "enabled": 1,
            "conversionCount": 0
        }
    ]
}

Get Link Lists from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/LinkList

Query Parameters

You can include several parameters to your GET query in order to receive the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active lists
filter disabled filtering by the specific list name
start 0 the number of items to skip

Request Example

GET  /api/3/LinkList/6941/links HTTP/1.1
Host: sms.messagewhiz.com
Content-Type: application/json
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.010940972,
    "result": [
        {
            "id": 6941,
            "links": [
                {
                    "linkId": 146746,
                    "url": "https://google.com"
                }, 
                {
                    "linkId": 146747,
                    "url": "https://youtube.com"
                }
            ]
        }
    ]
}

Get an array of Links from a specific Link List by ID:

GET https://sms.messagewhiz.com/api/3/LinkList/{id}/links

PUT Request Example

curl --location --request PUT 'https://sms.messagewhiz.com/api/3/LinkList/6941' \
--header 'apikey: <apikey>' \
--form 'doc=@/home/user/Downloads/SecondLinkList.csv' \
--form 'mapping={"0":"name", "1":"url"}' \
--form 'name=NewList'

PATCH Request Example

PATCH  /api/3/LinkList/6944 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "enabled": 1
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.009358444,
    "result": {
        "id": 6944,
        "enabled": 1
    }
}

If you want to partially update the resource, you can use:

PATCH https://sms.messagewhiz.com/api/3/linkList/{id}

Request Example

   DELETE /api/3/LinkList/6941 HTTP/1.1
   Host: sms.messagewhiz.com
   apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 2.519399016,
    "result": true
}

Remove a specific Link List from your MessageWhiz account by ID:

DELETE https://sms.messagewhiz.com/api/3/LinkList/{id}

Request Example

DELETE /api/3/LinkList/6940/links?[id]=146746 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.014643696,
    "result": true
}

To remove a Link from the Link List, include Link List ID in the query and specify Link ID as required parameter:

DELETE https://sms.messagewhiz.com/api/3/LinkList/{listID}/links?[id]={linkID}

Word Spinners

Word spinner is a token which enables randomizing the text in broadcast messages by randomly selecting from a predefined list of synonyms, so that the overall message and meaning are left intact while the wording is changed slightly. Just insert Word Spinner in a message as a token({{word_spinner:ID}}).

Create a Word Spinner

Example Request

POST /api/3/spinner HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "name":"Fit32",
    "words":  ["wo", "three", "spinner", "greeetinnngsss", "four", "test", "one", "five"]

}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.041090464,
    "result": {
        "name": "Fit32",
        "words": [
            "wo",
            "three",
            "spinner",
            "greeetinnngsss",
            "four",
            "test",
            "one",
            "five"
        ],
        "enabled": true,
        "id": 10520
    }
}

Create a Word Spinner from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/spinner

Request Body

In the request body specify details for the Word Spinner that will be created:

Get Word Spinners

Request Example

GET /api/3/spinner? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.018632456,
    "result": [
        {
            "words": [
                "wo",
                "three",
                "spinner",
                "greeetinnngsss",
                "four",
                "test",
                "one",
                "five"
            ],
            "enabled": true,
            "id": 10520,
            "name": "Fit32"
        }
    ]
}

Get Word Spinners from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/spinner

Query Parameters

You can include several parameters to your GET query in order to receive only the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active spinners
filter disabled filtering by the specific spinner name
start 0 the number of items to skip

Modify a Word Spinner

PUT Request Example

PUT /api/3/spinner/10519 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "name":"FirstSpinner"
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.014242532,
    "result": {
        "name": "FirstSpinner",
        "words": [
            "wo",
            "three",
            "spinner",
            "greeetinnngsss",
            "four",
            "test",
            "one",
            "five"
        ],
        "enabled": true,
        "id": 10520
    }
}

PATCH Request Example

PATCH /api/3/spinner/10520? HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "enabled": "0"
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.0242746,
    "result": {
        "enabled": 0
    }
}

To modify a specific Word Spinner, include its ID in the query:

PUT https://sms.messagewhiz.com/api/3/spinner/{id}

If you want to partially update the resource, you can use:

PATCH https://sms.messagewhiz.com/api/3/spinner/{id}

Request Body

In the request body specify the value you want to modify, for instance:

{ "name":"FirstSpinner" }

If the name array is specified in the request body for a PUT request, the previous words will be overwritten.

The Word Spinner might be disabled, by specifying it in the request body for a PATCH request:

{ "enabled": "0" }

Disable a Word Spinner

Request Example

DELETE /api/3/spinner/10520 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.00986104,
    "result": true
}

To remove a specific Word Spinner from your MessageWhiz account, include its ID in the query:

DELETE https://sms.messagewhiz.com/api/3/campaign/{id}

Templates

You can write the text of your message immediately before sending it, or use a predefined template for it. A message template is a message saved on the MessageWhiz platform that can be reused for new messages with similar content.

Create a Template

Example Request

POST /api/3/template HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "name":"FirstTemplate",
    "body": "HI!"
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.014043792,
    "result": {
        "id": 46126,
        "name": "FirstTemplate",
        "body": "HI!",
        "enabled": true
    }
}

Create a Template from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/template

Request Body

In the request body specify details for the Template that will be created:

Get Templates

Request Example

GET /api/3/template? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.007669944,
    "result": [
        {
            "enabled": true,
            "id": 46126,
            "user_id": 3191,
            "name": "FirstTemplate",
            "body": "HI!"
        },
        {
            "enabled": true,
            "id": 46125,
            "user_id": 3191,
            "name": "1",
            "body": "Test test {shorten_url}"
        }
    ]
}

Get Templates from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/template

Query Parameters

You can include several parameters to your GET query in order to receive only the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active templates
filter disabled filtering by the specific template name
start 0 the number of items to skip

Modify a Template

Request Example

PUT /api/3/template/46126 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "name":"AnotherTemplateName"
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.019078568,
    "result": {
        "id": 46126,
        "name": "AnotherTemplateName",
        "body": "HI!",
        "enabled": true
    }
}

To modify a specific Template, include its ID in the query:

PUT https://sms.messagewhiz.com/api/3/template/{id}

Request Body

In the request body specify the value you want to modify, for instance:

{ "name":"AnotherTemplateName" }

If the body is specified in the request body for a PUT request, the previous Template text will be overwritten.

Disable a Template

Request Example

DELETE /api/3/template/46126 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.01208964,
    "result": true
}

To remove a specific Template from your MessageWhiz account, include its ID in the query:

DELETE https://sms.messagewhiz.com/api/3/template/{id}

Triggers

One of the sending conditions that MessageWhiz provides is Trigger. Default triggers are used to postpone the sending of the message until a specific event occurs to trigger its transmission.

Create a Trigger

Example Request

POST /api/3/trigger HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "name":"newTrigger"
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.116146556,
    "result": {
        "id": 5677,
        "name": "newTrigger",
        "uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
        "enabled": 1,
        "short_url": "https://0nz0.com/jBR4d",
        "trigger_type_id": 1
    }
}

Create a Trigger from your MessageWhiz account:

POST https://sms.messagewhiz.com/api/3/trigger

Request Body

In the request body specify the Trigger "name" that will be created.

In response you will receive a short_url. The message or broadcast will not be sent until the link is clicked on or activated.

Get a Trigger

Request Example

GET /api/3/trigger? HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.007109016,
    "result": [
        {
            "id": 5677,
            "name": "newTrigger",
            "uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
            "enabled": 1,
            "short_url": "https://0nz0.com/jBR4d",
            "trigger_type_id": 1,
            "details": null,
            "date": null,
            "flight_details.flight_number": null,
            "flight_details.arrival_date": null
        }
    ]
}

Get Trigger from your MessageWhiz account:

GET https://sms.messagewhiz.com/api/3/trigger

Query Parameters

You can include several parameters to your GET query in order to receive only the data you need.

Parameter Default Description
limit 10 the number of items to fetch
enabled true fetch only active triggers
filter disabled filtering by the specific trigger name
start 0 the number of items to skip

Modify a Trigger

Request Example

PUT /api/3/trigger/5677 HTTP/1.1
Host: sms.messagewhiz.com
apikey:  <apikey>
Content-Type: application/json

{
    "name":"#"
}

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.011503284,
    "result": {
        "id": 5677,
        "name": "#",
        "uuid": "1fbea646-7d1e-4475-9f50-26aec1bf3482",
        "enabled": 1,
        "short_url": "https://0nz0.com/jBR4d"
    }
}

To modify a specific Trigger include its ID in the query:

PUT https://sms.messagewhiz.com/api/3/trigger/{id}

Request Body

In the request body specify the new value of name, for instance:

{ "name":"#" }

Disable a Trigger

Request Example

DELETE /api/3/trigger/5677 HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>

Response Example (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.014187964,
    "result": true
}

To remove a specific Trigger from your MessageWhiz account, include its ID in the query:

DELETE https://sms.messagewhiz.com/api/3/trigger/{id}

Delivery report

Get a delivery report

Example Request

POST /api/3/DeliveryReport HTTP/1.1
Host: sms.messagewhiz.com
apikey: <apikey>
Content-Type: application/json

{
    "bid": 123123
}

Example Response (200 OK)

{
    "errorCode": 0,
    "errorMessage": "",
    "errorType": "",
    "executionTime": 0.176761073,
    "result": [
        {
            "broadcast_id": 123123,
            "sent": 0,
            "delivered": 1,
            "undelivered": 0,
            "rejected": 0,
            "expired": 0,
            "failed": 0
        }
    ]
}

To get the delivery report of a certain broadcast:

POST https://sms.messagewhiz.com/api/3/DeliveryReport

You should pass only one parameter in the body

In case the broadcast is a V3 smart broadcast (Manual/CTR threshold) each segment DLR will be shown in a separate object in the response.

DLR to webhook

Example Response for broadcasts

{
   "dlrs" : [ {   "segment_id":100001,
        "_id":"611f9cdf8d0a4976d8d8462aaaac",
        "broadcast_id":1100001,
        "recipient":"3801100001",
        "price":11.8,
        "task_state":2,
        "updated":1629461739834

    },
    {   "segment_id":100002,
        "_id":"611f9cdf8d0a4976d8d8462aaaaad",
        "broadcast_id":1100002,
        "recipient":"3801100002",
        "price":11.8,
        "task_state":2,
        "updated":1629461739834
    },
    {   "segment_id":100003,
        "_id":"611f9cdf8d0a4976d8d8462aaae",
        "broadcast_id":1100003,
        "recipient":"3801100003",
        "price":11.8,
        "task_state":2,
        "updated":1629461739834
    }
    ],
    "custom_parameter":"1234abcd5678efgh"
}

Example Response for tiny singles

{
   "dlrs" : [ 
    {   "segment_id":100005,
        "_id":"611f9cdf8d0a4976s8d8462aaaac",
        "broadcast_id":1100005,
        "recipient":"3801100001",
        "price":1.8,
        "task_state":2,
        "updated":1629461732834
    }],
    "pduDLR": {
        "sent_count": 2,
        "delivered_count": 1
    }
}

API users can receive DLR reports to a defined URL with 2 timeout parameters: T1 and T2. Currently this feature is enabled only after configurations by the technical team. Each client should provide Webhook URL and a T1 parameter (parameter T2 is optional). Minimum value for parameters T1 and T2 is 3 minutes.

Configuration Parameters

Required parameters

Optional parameters

Response parameters

0 - Sent
2 - Delivered
9 - Failed
8 - Rejected
5 - Undelivered
3 - Expired

Example:

"pduDLR": {
"sent_count": 1,
"delivered_count": 2,
"undelivered_count": 0, //will not be present in response
"rejected_count": 0, //will not be present in response
"expired_count": 0 //will not be present in response
}

Response Error Messages

You may receive the following error codes from MessageWhiz API in response to your request:

Error Code Meaning
400 Bad Request -- Invalid parameters specified
401 Unauthorized -- API key is missing or invalid
403 Forbidden -- User/company is either disabled or doesn't have enough permissions
404 Not found -- An entity is not found
409 Duplicate entry